> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/guides/api-reference/agents.md).

# Agents

Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books.

## List Agents

> Lists all persisted agent IDs.\
> \
> Returns the IDs of agents that have been saved to disk.\
> Agents that exist only in memory (not yet saved) are not included.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListAgentsResponse":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1AgentDescriptor"},"description":"The agents on this page, with their metadata."},"total_size":{"type":"integer","format":"int32","description":"Total agents matching the parent scope AND query AND filter, across all\npages."},"order_by":{"type":"string","description":"The order applied to this page, normalised (e.g. \"updated_at desc\").\nThe surface default when the request left `order_by` empty."}},"description":"Response message for ListAgents."},"agentsV1AgentDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"The agent's unique identifier."},"name":{"type":"string","description":"The agent's display name."},"description":{"type":"string","description":"Optional description of the agent's purpose."},"read_only":{"type":"boolean","description":"Whether this agent is read-only (e.g. the default agent)."},"latest_version":{"type":"string","format":"uint64","description":"Latest version number, if the store supports versioning."},"latest_tags":{"type":"array","items":{"type":"string"},"description":"Tags applied to the latest version."},"last_updated_at":{"type":"string","format":"date-time","description":"When the latest version was created (last update time)."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"created_at":{"type":"string","format":"date-time","description":"When the agent was created (first save)."},"rating":{"type":"number","format":"double","description":"Aggregated user-feedback rating in [0, 1] (Wilson lower bound), projected\nto the latest version. Absent when no feedback has been recorded."},"abilities":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Ability"},"description":"The agent's abilities, as shown on the agent card. Empty when the\nagent has no abilities."},"icon":{"type":"string","description":"The agent's icon, as a kebab-case Lucide icon name. Empty when the\nagent has no icon."},"stats":{"type":"object","additionalProperties":{"type":"string"},"description":"Derived, presentational metadata about the agent, e.g.\n{\"model\": \"gpt-4o\", \"generator_kind\": \"openai\", \"tool_count\": \"12\",\n\"context_window\": \"128000\"}. Keys are open-ended; clients read the\nones they recognize and ignore the rest. Values are strings; numeric\nvalues are stringified. A key is absent when it has no value for the\nagent (e.g. an agent with no fixed model omits \"model\")."},"has_plan":{"type":"boolean","description":"Whether the agent defines a base plan. A promptless schedule requires\none (each run executes the plan), so clients gate that affordance on it."},"labels":{"type":"array","items":{"type":"string"},"description":"Freeform labels describing the agent as a whole, e.g. \"finance\",\n\"internal-tool\". Unlike `latest_tags`, which names one immutable\nversion, these belong to the agent and do not change as versions come\nand go."}},"description":"Descriptor for an agent with basic metadata."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1Ability":{"type":"object","properties":{"name":{"type":"string","description":"Short label, e.g. \"web search\", \"PDF editing\", \"team memory\"."},"icon":{"type":"string","description":"Icon identifier, as a kebab-case Lucide icon name (e.g. \"file-text\",\n\"git-branch\", \"map-pin\")."},"description":{"type":"string","description":"Optional one-line description for a tooltip."}},"description":"A single human-readable agent capability shown on the agent card."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents":{"get":{"summary":"List Agents","description":"Lists all persisted agent IDs.\n\nReturns the IDs of agents that have been saved to disk.\nAgents that exist only in memory (not yet saved) are not included.","operationId":"ListAgents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListAgentsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"Max agents to return; 0 / unset = all in one page.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page","description":"1-based page number; 0 / unset = page 1.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"query","description":"Free-text search over id / name / description; empty = no filter.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression over the fields advertised in the response's\n`filter_schema` (e.g. `generator_kind in [\"openai\"] && read_only == false`).\nEmpty = no filter.","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Sort order, e.g. \"name\" or \"updated_at desc\". One of the keys advertised\nin the schema endpoint's `sort_fields`, optionally followed by \"asc\"\n(default) or \"desc\". Empty = the surface's default order.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Agent

> Creates a new agent with the given name.\
> \
> The agent ID is derived from the name (lowercase, dashed, URL-friendly).

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1CreateAgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"The newly created agent's unique identifier."},"name":{"type":"string","description":"The agent's display name."},"version":{"type":"string","format":"uint64","description":"The version number of the newly created agent (always 1 for new agents)."}},"description":"Response message for CreateAgent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsV1CreateAgentRequest":{"type":"object","properties":{"name":{"type":"string","description":"Required. The display name for the new agent.\nThe agent ID will be derived from this name (lowercase, dashed)."}},"description":"Request to create a new agent.\n\nThe agent is created with an empty template (no generator, no tools, no\nmemory blocks, no variables). The agent is queryable but not runnable\nuntil a thread sets the desired configuration as overrides and deploys\nto produce a new version."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents":{"post":{"summary":"Create Agent","description":"Creates a new agent with the given name.\n\nThe agent ID is derived from the name (lowercase, dashed, URL-friendly).","operationId":"CreateAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1CreateAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1CreateAgentRequest"}}},"description":"Request to create a new agent.\n\nThe agent is created with an empty template (no generator, no tools, no\nmemory blocks, no variables). The agent is queryable but not runnable\nuntil a thread sets the desired configuration as overrides and deploys\nto produce a new version.","required":true},"tags":["Agents"]}}}}
```

## List Threads (Hermes, workspace)

> Lists all threads for an agent.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads":{"get":{"summary":"List Threads (Hermes, workspace)","description":"Lists all threads for an agent.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"HermesListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Hermes, workspace)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads":{"post":{"summary":"Create Thread (Hermes, workspace)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"HermesCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread (Hermes, workspace)

> Gets a thread by ID.\
> \
> Returns thread metadata and event count without loading the full event history.\
> Returns NOT\_FOUND if the thread doesn't exist.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`GetThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}":{"get":{"summary":"Get Thread (Hermes, workspace)","description":"Gets a thread by ID.\n\nReturns thread metadata and event count without loading the full event history.\nReturns NOT_FOUND if the thread doesn't exist.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `GetThread` on `/agents/{agent_id}`.","operationId":"HermesGetThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Thread (Hermes, workspace)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Hermes, workspace)","description":"Deletes a thread and all its events.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"HermesDeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Thread (Hermes, workspace)

> Updates a thread's title and/or description.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`UpdateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional new title for the thread."},"description":{"type":"string","description":"Optional new description for the thread."}},"description":"Request to update a thread's metadata."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}":{"patch":{"summary":"Update Thread (Hermes, workspace)","description":"Updates a thread's title and/or description.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `UpdateThread` on `/agents/{agent_id}`.","operationId":"HermesUpdateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread Context (Hermes, workspace)

> Gets thread context information including all context items with token counts.\
> \
> Returns a unified view of all items contributing to the context window:\
> \- Memory blocks (fixed and volatile)\
> \- Enabled tools (fixed)\
> \- Conversation history (compactable)\
> \
> Each item includes its token count for context budget management.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`GetThreadContext\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetThreadContextResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ContextItem"},"description":"List of context items contributing to the thread's context window.","readOnly":true},"model_info":{"$ref":"#/components/schemas/agentsV1ModelInfo"},"summary":{"$ref":"#/components/schemas/agentsV1ContextSummary"},"auto_compact_tokens":{"type":"integer","format":"int64","description":"Prompt token count at which the next completed turn triggers\nauto-compaction.\n\nAbsent when no compactor is configured, in which case auto-compaction\nnever fires, or when the model does not report a context window.","readOnly":true}},"description":"Response containing thread context information."},"agentsV1ContextItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the context item.","readOnly":true},"label":{"type":"string","description":"Human-readable label for display.","readOnly":true},"token_count":{"type":"integer","format":"int64","description":"Number of tokens this item consumes.","readOnly":true},"category":{"$ref":"#/components/schemas/agentsV1ContextCategory"},"memory_block":{"$ref":"#/components/schemas/agentsV1MemoryBlockRef"},"tool":{"$ref":"#/components/schemas/agentsV1ToolRef"}},"description":"A single item contributing to the thread's context window."},"agentsV1ContextCategory":{"type":"string","enum":["CONTEXT_CATEGORY_UNSPECIFIED","CONTEXT_CATEGORY_FIXED","CONTEXT_CATEGORY_VOLATILE","CONTEXT_CATEGORY_COMPACTABLE"],"default":"CONTEXT_CATEGORY_UNSPECIFIED","description":"Category of context items for token budget management.\n\n - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category.\n - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools).\n - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks).\n - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history)."},"agentsV1MemoryBlockRef":{"type":"object","properties":{"block_id":{"type":"string","description":"The unique block identifier (deterministic hash of block name).","readOnly":true},"type":{"type":"string","description":"The block type (e.g., \"text\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the block type.","readOnly":true},"description":{"type":"string","description":"Description of the memory block.","readOnly":true},"scope":{"$ref":"#/components/schemas/agentsV1ScopeLevel"},"mutable":{"type":"boolean","description":"Whether the block is mutable.","readOnly":true}},"description":"Lightweight memory block reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits content and config to keep responses lightweight."},"agentsV1ScopeLevel":{"type":"string","enum":["SCOPE_LEVEL_UNSPECIFIED","SCOPE_LEVEL_AGENT","SCOPE_LEVEL_THREAD","SCOPE_LEVEL_USER"],"default":"SCOPE_LEVEL_UNSPECIFIED","description":"The scope level for a memory block's content storage.\n\n - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT).\n - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads.\n - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content.\n - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content,\nwhich follows them across all of their threads with the agent and is\ninvisible to other users. Only kinds whose allowed_scopes include it\n(or list no restriction) accept it."},"agentsV1ToolRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool identifier (hash of the original tool name).","readOnly":true},"name":{"type":"string","description":"The tool name (may be adapted name if adapters are applied).","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted.","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations).","readOnly":true}},"description":"Lightweight tool reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits parameters_schema to keep responses lightweight."},"agentsV1ModelInfo":{"type":"object","properties":{"model_id":{"type":"string","description":"Model identifier (e.g., \"gpt-4o\", \"claude-3-opus\").","readOnly":true},"max_context_tokens":{"type":"integer","format":"int64","description":"Maximum context length in tokens.","readOnly":true},"max_output_tokens":{"type":"integer","format":"int64","description":"Maximum output tokens.","readOnly":true},"supports_vision":{"type":"boolean","description":"Whether the model supports vision/images.","readOnly":true},"supports_tools":{"type":"boolean","description":"Whether the model supports tool/function calling.","readOnly":true},"supports_structured_output":{"type":"boolean","description":"Whether the model supports structured output (JSON mode).","readOnly":true},"supports_streaming":{"type":"boolean","description":"Whether the model supports streaming responses.","readOnly":true},"supports_reasoning":{"type":"boolean","description":"Whether the model supports reasoning (chain-of-thought).","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"GPT-4o\", \"Claude Sonnet 4.5\").","readOnly":true},"family":{"type":"string","description":"Model family grouping (e.g., \"gpt-4o\", \"claude-4.5\", \"qwen2\").","readOnly":true},"license":{"type":"string","description":"License information (e.g., for open-weight models).","readOnly":true},"parameter_count":{"type":"string","format":"uint64","description":"Number of model parameters.","readOnly":true},"quantization":{"type":"string","description":"Quantization level (e.g., \"Q4_K_M\", \"Q8_0\").","readOnly":true},"supports_documents":{"type":"boolean","description":"Whether the model supports document inputs (PDFs, text files).","readOnly":true},"max_inline_artifact_bytes":{"type":"string","format":"uint64","description":"Maximum size of a single tool result that can be inlined into a\ngeneration request, in raw bytes. Already accounts for base64 expansion\nand a safety margin for request overhead.","readOnly":true},"deprecated":{"type":"boolean","description":"Whether the model is deprecated: still usable, but slated for retirement.","readOnly":true},"retired":{"type":"boolean","description":"Whether the model is retired: loadable (so existing threads/agents don't\nbreak) but generation is refused.","readOnly":true},"replacement_model":{"type":"string","description":"Recommended replacement model id when deprecated or retired.","readOnly":true},"pricing":{"$ref":"#/components/schemas/agentsV1ModelPricing"}},"description":"Information about a model and its capabilities."},"agentsV1ModelPricing":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DatedRates"},"description":"Effective-dated rate rows. Windows should not overlap; if they do, the\nearliest-starting matching row wins so the outcome is deterministic.","readOnly":true}},"description":"Complete pricing knowledge for one model: its effective-dated rate rows.\n\nAn empty `rows` list is a valid \"priced at zero\" card for local models —\ndistinct from a model carrying no `ModelPricing` at all, which means its\ncost is unknown, not free."},"agentsV1DatedRates":{"type":"object","properties":{"effective_from":{"type":"string","format":"date-time","description":"Inclusive start of this row's validity. Absent = open-ended past.","readOnly":true},"effective_until":{"type":"string","format":"date-time","description":"Exclusive end of this row's validity. Absent = open-ended future.","readOnly":true},"base":{"$ref":"#/components/schemas/agentsV1RateCard"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1TierRates"},"description":"Long-context tiers: token-threshold bands above `base`, ascending by\n`threshold_tokens`. Empty = flat pricing. A request's total prompt size\nselects the highest tier whose threshold it reaches, or `base` below\nevery threshold.","readOnly":true}},"description":"One effective-dated pricing row: the rates in force during a validity\nwindow. A model whose price changes on a schedule carries several rows\ndiffering only in rates and effective bounds."},"agentsV1RateCard":{"type":"object","properties":{"input_per_mtok":{"type":"number","format":"double","description":"Fresh (uncached) input, USD per million tokens.","readOnly":true},"output_per_mtok":{"type":"number","format":"double","description":"Output, USD per million tokens. Includes reasoning/thinking tokens.","readOnly":true},"cache_read_per_mtok":{"type":"number","format":"double","description":"Tokens served from cache, USD per million tokens.","readOnly":true},"cache_write_per_mtok":{"type":"number","format":"double","description":"Cache writes at any TTL, USD per million tokens — for providers with a\nsingle write rate regardless of TTL.","readOnly":true},"cache_write_by_ttl":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWriteRate"},"description":"Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`.","readOnly":true}},"description":"One complete set of USD-per-million-token rates. A missing cache rate is\nnot zero — it means the dimension is unpublished, and cost computation\nfalls back loudly (billed at the fresh-input rate, flagged estimated)."},"agentsV1CacheWriteRate":{"type":"object","properties":{"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket,\n3600 for a 1-hour bucket).","readOnly":true},"per_mtok":{"type":"number","format":"double","description":"USD per million tokens written into this bucket.","readOnly":true}},"description":"USD rate for cache writes at one specific TTL bucket."},"agentsV1TierRates":{"type":"object","properties":{"threshold_tokens":{"type":"integer","format":"int64","description":"Prompt-size threshold (total prompt tokens: fresh + cache read + cache\nwrite) at which these rates activate.","readOnly":true},"card":{"$ref":"#/components/schemas/agentsV1RateCard"}},"description":"One long-context tier band: requests whose total prompt tokens meet or\nexceed `threshold_tokens` (and fall below the next tier's threshold, when\none exists) bill the entire request — every class, input and output — at\n`card` instead of the base card."},"agentsV1ContextSummary":{"type":"object","properties":{"fixed_tokens":{"type":"integer","format":"int64","description":"Tokens used by fixed context (immutable memory + tools).","readOnly":true},"volatile_tokens":{"type":"integer","format":"int64","description":"Tokens used by volatile context (mutable memory).","readOnly":true},"compactable_tokens":{"type":"integer","format":"int64","description":"Tokens used by compactable context (conversation).","readOnly":true},"total_used_tokens":{"type":"integer","format":"int64","description":"Total tokens currently in use.","readOnly":true},"available_tokens":{"type":"integer","format":"int64","description":"Tokens available before hitting the context limit.","readOnly":true}},"description":"Summary of token usage by category."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/context":{"get":{"summary":"Get Thread Context (Hermes, workspace)","description":"Gets thread context information including all context items with token counts.\n\nReturns a unified view of all items contributing to the context window:\n- Memory blocks (fixed and volatile)\n- Enabled tools (fixed)\n- Conversation history (compactable)\n\nEach item includes its token count for context budget management.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`.","operationId":"HermesGetThreadContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetThreadContextResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"The thread ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events (Hermes, workspace)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Hermes, workspace)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"HermesGetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message And Wait (Hermes, workspace)

> Sends a message and streams back response events synchronously.\
> \
> This RPC adds user input to the specified thread and returns a stream\
> of events representing the assistant's response. Events include output text,\
> tool calls, and completion metadata.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`SendMessageAndWait\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageSyncBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message and stream response events synchronously."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/events":{"post":{"summary":"Send Message And Wait (Hermes, workspace)","description":"Sends a message and streams back response events synchronously.\n\nThis RPC adds user input to the specified thread and returns a stream\nof events representing the assistant's response. Events include output text,\ntool calls, and completion metadata.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`.","operationId":"HermesSendMessageAndWait","responses":{"200":{"description":"A successful response.(streaming responses)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/agentsV1Event"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"Stream result of v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageSyncBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Set Thread Feedback (Hermes, workspace)

> Sets feedback (like/dislike) for a generation response.\
> \
> Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\
> Setting the same feedback that already exists is a no-op.\
> Use FEEDBACK\_TYPE\_UNSPECIFIED to clear existing feedback.\
> \
> Feedback is stored with the thread and is purely for analytics/UI purposes.\
> It is not visible to the LLM.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`SetThreadFeedback\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SetFeedbackResponse":{"type":"object","properties":{"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"previous_feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Response for setting feedback on a generation."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSetFeedbackBody":{"type":"object","properties":{"generation_id":{"type":"string","description":"Required. The generation ID (from GenerationComplete.id)."},"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Request to set feedback for a generation response."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/feedback":{"post":{"summary":"Set Thread Feedback (Hermes, workspace)","description":"Sets feedback (like/dislike) for a generation response.\n\nFeedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\nSetting the same feedback that already exists is a no-op.\nUse FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback.\n\nFeedback is stored with the thread and is purely for analytics/UI purposes.\nIt is not visible to the LLM.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`.","operationId":"HermesSetThreadFeedback","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SetFeedbackResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread containing the generation.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSetFeedbackBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Message (Hermes, workspace)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/input":{"post":{"summary":"Send Message (Hermes, workspace)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"HermesSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Hermes, workspace)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Hermes, workspace)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"HermesStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## List Sub Agents (Hermes, workspace)

> Lists sub-agents configured for a thread.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`ListSubAgents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListSubAgentsResponse":{"type":"object","properties":{"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"The sub-agents configured for the thread."},"is_customized":{"type":"boolean","description":"Whether this represents a per-thread customization (vs inherited from agent)."}},"description":"Response message for ListSubAgents."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/sub-agents":{"get":{"summary":"List Sub Agents (Hermes, workspace)","description":"Lists sub-agents configured for a thread.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`.","operationId":"HermesListSubAgents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListSubAgentsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread whose sub-agents to list.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Tool Call (Hermes, workspace)

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`SendToolCall\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call (Hermes, workspace)","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `SendToolCall` on `/agents/{agent_id}`.","operationId":"HermesSendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result (Hermes, workspace)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Hermes, workspace)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"HermesSendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File (Hermes, workspace)

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`UploadThreadFile\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File (Hermes, workspace)","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`.","operationId":"HermesUploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Compact Thread (Hermes, workspace)

> Starts context compaction for a thread.\
> \
> Compaction summarizes conversation history to reduce context size while\
> preserving essential information. This RPC emits a CompactStart event\
> and returns the compact\_id for tracking.\
> \
> The actual compaction is performed asynchronously. Once complete, a\
> CompactComplete event with the summary content should be added to the\
> thread using the returned compact\_id.\
> \
> While compaction is in progress (CompactStart without CompactComplete),\
> the UI should block user input.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`CompactThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StartCompactionResponse":{"type":"object","properties":{"compact_id":{"type":"string","description":"The unique ID assigned to this compaction operation."}},"description":"Response for starting context compaction."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStartCompactionBody":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"Optional. The event ID from which to start compaction.\nEvents from this ID onwards (inclusive) will be compacted.\nIf not specified, the entire conversation is compacted."}},"description":"Request to start context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. A CompactStart event is emitted immediately,\nand an external compaction process should later emit CompactComplete with the\nsummary."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:compact":{"post":{"summary":"Compact Thread (Hermes, workspace)","description":"Starts context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. This RPC emits a CompactStart event\nand returns the compact_id for tracking.\n\nThe actual compaction is performed asynchronously. Once complete, a\nCompactComplete event with the summary content should be added to the\nthread using the returned compact_id.\n\nWhile compaction is in progress (CompactStart without CompactComplete),\nthe UI should block user input.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `CompactThread` on `/agents/{agent_id}`.","operationId":"HermesCompactThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StartCompactionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to compact.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStartCompactionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Fork Thread (Hermes, workspace)

> Forks (duplicates) a thread with all its data.\
> \
> Creates a new thread that is a complete copy of the source thread,\
> including events, feedback, memory customizations, scratchpad, plan,\
> and template config customizations.\
> Returns FAILED\_PRECONDITION if the source thread is currently generating.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`ForkThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceForkThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the new thread. Defaults to \"Fork of {source_title}\"."}},"description":"Request message for ForkThread (duplicate a thread with all its data)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:fork":{"post":{"summary":"Fork Thread (Hermes, workspace)","description":"Forks (duplicates) a thread with all its data.\n\nCreates a new thread that is a complete copy of the source thread,\nincluding events, feedback, memory customizations, scratchpad, plan,\nand template config customizations.\nReturns FAILED_PRECONDITION if the source thread is currently generating.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `ForkThread` on `/agents/{agent_id}`.","operationId":"HermesForkThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The source thread to fork.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceForkThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stop Thread (Hermes, workspace)

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`StopThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread (Hermes, workspace)","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `StopThread` on `/agents/{agent_id}`.","operationId":"HermesStopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread (Hermes, workspace)

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.\
> \
> Targets the built-in \`hermes\` agent in the workspace scope; the generic form is \`WakeThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/hermes/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread (Hermes, workspace)","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.\n\nTargets the built-in `hermes` agent in the workspace scope; the generic form is `WakeThread` on `/agents/{agent_id}`.","operationId":"HermesWakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Threads (Smith, workspace)

> Lists all threads for an agent.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads":{"get":{"summary":"List Threads (Smith, workspace)","description":"Lists all threads for an agent.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"SmithListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Smith, workspace)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads":{"post":{"summary":"Create Thread (Smith, workspace)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"SmithCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread (Smith, workspace)

> Gets a thread by ID.\
> \
> Returns thread metadata and event count without loading the full event history.\
> Returns NOT\_FOUND if the thread doesn't exist.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}":{"get":{"summary":"Get Thread (Smith, workspace)","description":"Gets a thread by ID.\n\nReturns thread metadata and event count without loading the full event history.\nReturns NOT_FOUND if the thread doesn't exist.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetThread` on `/agents/{agent_id}`.","operationId":"SmithGetThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Thread (Smith, workspace)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Smith, workspace)","description":"Deletes a thread and all its events.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"SmithDeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Thread (Smith, workspace)

> Updates a thread's title and/or description.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`UpdateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional new title for the thread."},"description":{"type":"string","description":"Optional new description for the thread."}},"description":"Request to update a thread's metadata."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}":{"patch":{"summary":"Update Thread (Smith, workspace)","description":"Updates a thread's title and/or description.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `UpdateThread` on `/agents/{agent_id}`.","operationId":"SmithUpdateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Artifacts (Smith, workspace)

> Lists artifacts with optional filters.\
> Supports S3-style delimiter for folder navigation.\
> Thread ID is required for variable-scoped artifact access.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`ListArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListArtifactsResponse":{"type":"object","properties":{"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Artifact"},"description":"Artifacts matching the filter."},"common_prefixes":{"type":"array","items":{"type":"string"},"description":"Common prefixes (\"folders\") when delimiter is set."}},"description":"Response for ListArtifacts."},"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts":{"get":{"summary":"List Artifacts (Smith, workspace)","description":"Lists artifacts with optional filters.\nSupports S3-style delimiter for folder navigation.\nThread ID is required for variable-scoped artifact access.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `ListArtifacts` on `/agents/{agent_id}`.","operationId":"SmithListArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"prefix","description":"Optional. Filter by URI prefix (e.g., \"workspace://src/\").\nIf not specified, lists from all stores.","in":"query","required":false,"schema":{"type":"string"}},{"name":"delimiter","description":"Optional. Delimiter for S3-style folder grouping (typically \"/\").","in":"query","required":false,"schema":{"type":"string"}},{"name":"mime_type","description":"Optional. Filter by MIME type prefix (e.g., \"text/\", \"image/\").","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","description":"Optional. Maximum number of results.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}}],"tags":["Agents"]}}}}
```

## Get Artifact (Smith, workspace)

> Gets artifact metadata by URI.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetArtifact\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}":{"get":{"summary":"Get Artifact (Smith, workspace)","description":"Gets artifact metadata by URI.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifact` on `/agents/{agent_id}`.","operationId":"SmithGetArtifact","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Artifact"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Artifact (Smith, workspace)

> Creates or updates an artifact.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`UpdateArtifact\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateArtifactBody":{"type":"object","properties":{"mime_type":{"type":"string","description":"Required. The MIME type."},"data":{"type":"string","format":"byte","description":"Required. The artifact content."},"description":{"type":"string","description":"Optional description."}},"description":"Request for UpdateArtifact.","required":["mime_type","data"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}":{"put":{"summary":"Update Artifact (Smith, workspace)","description":"Creates or updates an artifact.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `UpdateArtifact` on `/agents/{agent_id}`.","operationId":"SmithUpdateArtifact","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Artifact"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateArtifactBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete Artifact (Smith, workspace)

> Deletes an artifact by URI.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`DeleteArtifact\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}":{"delete":{"summary":"Delete Artifact (Smith, workspace)","description":"Deletes an artifact by URI.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `DeleteArtifact` on `/agents/{agent_id}`.","operationId":"SmithDeleteArtifact","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Artifact Content (Smith, workspace)

> Gets artifact content by URI.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetArtifactContent\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ArtifactContentResponse":{"type":"object","properties":{"artifact":{"$ref":"#/components/schemas/agentsV1Artifact"},"data":{"type":"string","format":"byte","description":"The raw content bytes."}},"description":"Response for GetArtifactContent."},"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}:content":{"get":{"summary":"Get Artifact Content (Smith, workspace)","description":"Gets artifact content by URI.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifactContent` on `/agents/{agent_id}`.","operationId":"SmithGetArtifactContent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ArtifactContentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Artifact Diff (Smith, workspace)

> Gets the diff for a single staged artifact.\
> \
> Returns the unified diff for a specific artifact if it has staged changes.\
> Returns empty diff for binary files or if no changes exist.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetArtifactDiff\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetArtifactDiffResponse":{"type":"object","properties":{"has_changes":{"type":"boolean","description":"Whether this artifact has staged changes."},"change":{"$ref":"#/components/schemas/agentsV1StagedChange"},"diff":{"type":"string","description":"Unified diff content.\nEmpty for binary files, deleted artifacts, or if no changes."}},"description":"Response for GetArtifactDiff."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts/{artifact_uri}:diff":{"get":{"summary":"Get Artifact Diff (Smith, workspace)","description":"Gets the diff for a single staged artifact.\n\nReturns the unified diff for a specific artifact if it has staged changes.\nReturns empty diff for binary files or if no changes exist.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifactDiff` on `/agents/{agent_id}`.","operationId":"SmithGetArtifactDiff","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetArtifactDiffResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Commit Artifacts (Smith, workspace)

> Commits staged artifact changes to the underlying store.\
> \
> Persists all staged changes (additions, modifications, deletions) to\
> the underlying store. For stores without staging, this is a no-op.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`CommitArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1CommitArtifactsResponse":{"type":"object","properties":{"committed_count":{"type":"integer","format":"int64","description":"Number of artifacts committed."},"additions":{"type":"integer","format":"int64","description":"Number of additions committed."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications committed."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions committed."},"version":{"type":"string","description":"New artifact version produced by this commit, if the store versions its\ncontents. Absent for stores without a version concept."}},"description":"Response for CommitArtifacts."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCommitArtifactsBody":{"type":"object","properties":{"prefix":{"type":"string","description":"Optional. Store prefix to limit commit scope (e.g., \"workspace://\").\nIf not specified, commits all staged changes across all stores."}},"description":"Request for CommitArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:commit":{"post":{"summary":"Commit Artifacts (Smith, workspace)","description":"Commits staged artifact changes to the underlying store.\n\nPersists all staged changes (additions, modifications, deletions) to\nthe underlying store. For stores without staging, this is a no-op.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `CommitArtifacts` on `/agents/{agent_id}`.","operationId":"SmithCommitArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1CommitArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCommitArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Diff Artifacts (Smith, workspace)

> Gets staged artifact changes with optional diff content.\
> \
> Returns information about artifacts that have been modified but not yet\
> committed. For stores with staging enabled, this shows pending changes.\
> For stores without staging, returns an empty response.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`DiffArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DiffArtifactsResponse":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DiffEntry"},"description":"List of staged changes with optional diff content."},"total_changes":{"type":"integer","format":"int64","description":"Total number of staged changes."},"additions":{"type":"integer","format":"int64","description":"Number of additions."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions."}},"description":"Response for DiffArtifacts."},"agentsV1DiffEntry":{"type":"object","properties":{"change":{"$ref":"#/components/schemas/agentsV1StagedChange"},"diff":{"type":"string","description":"Unified diff content (only if include_content was true).\nEmpty for binary files or deleted artifacts."}},"description":"A diff entry with optional content."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDiffArtifactsBody":{"type":"object","properties":{"prefix":{"type":"string","description":"Optional. Store prefix to limit diff scope (e.g., \"workspace://\").\nIf not specified, returns diff for all stores."},"include_content":{"type":"boolean","description":"Optional. Include unified diff content for each change.\nDefault is false (summary only)."}},"description":"Request for DiffArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:diff":{"post":{"summary":"Diff Artifacts (Smith, workspace)","description":"Gets staged artifact changes with optional diff content.\n\nReturns information about artifacts that have been modified but not yet\ncommitted. For stores with staging enabled, this shows pending changes.\nFor stores without staging, returns an empty response.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `DiffArtifacts` on `/agents/{agent_id}`.","operationId":"SmithDiffArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DiffArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDiffArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Discard Artifacts (Smith, workspace)

> Discards all staged artifact changes without committing.\
> \
> Clears all pending changes (additions, modifications, deletions) from\
> the staging area. For stores without staging, this is a no-op.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`DiscardArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DiscardArtifactsResponse":{"type":"object","properties":{"discarded_count":{"type":"integer","format":"int64","description":"Number of artifacts discarded."},"additions":{"type":"integer","format":"int64","description":"Number of additions discarded."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications discarded."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions discarded."}},"description":"Response for DiscardArtifacts."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDiscardArtifactsBody":{"type":"object","properties":{},"description":"Request for DiscardArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:discard":{"post":{"summary":"Discard Artifacts (Smith, workspace)","description":"Discards all staged artifact changes without committing.\n\nClears all pending changes (additions, modifications, deletions) from\nthe staging area. For stores without staging, this is a no-op.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `DiscardArtifacts` on `/agents/{agent_id}`.","operationId":"SmithDiscardArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DiscardArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDiscardArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Grep Artifacts (Smith, workspace)

> Searches artifact contents using regex pattern matching.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GrepArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GrepArtifactsResponse":{"type":"object","properties":{"pattern":{"type":"string","description":"The pattern that was searched."},"match_count":{"type":"integer","format":"int64","description":"Total number of matches found (may exceed matches size if limited)."},"matches":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1GrepMatch"},"description":"The matches (may be limited by request limit)."}},"description":"Response for GrepArtifacts."},"agentsV1GrepMatch":{"type":"object","properties":{"id":{"type":"string","description":"Artifact ID containing the match.","readOnly":true},"name":{"type":"string","description":"Artifact name/path.","readOnly":true},"line":{"type":"integer","format":"int64","description":"Line number (1-indexed).","readOnly":true},"content":{"type":"string","description":"The matching line content.","readOnly":true},"context_before":{"type":"array","items":{"type":"string"},"description":"Lines before the match (context).","readOnly":true},"context_after":{"type":"array","items":{"type":"string"},"description":"Lines after the match (context).","readOnly":true}},"description":"A single grep match within an artifact."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceGrepArtifactsBody":{"type":"object","properties":{"pattern":{"type":"string","description":"Required. Regex pattern to search for."},"prefix":{"type":"string","description":"Optional. URI prefix to limit search scope (e.g., \"workspace://src/\")."},"glob":{"type":"string","description":"Optional. Glob pattern to filter files (e.g., \"*.rs\")."},"ignore_case":{"type":"boolean","description":"Optional. Case-insensitive search."},"context_lines":{"type":"integer","format":"int64","description":"Optional. Number of context lines before/after each match."},"limit":{"type":"integer","format":"int64","description":"Optional. Maximum number of matches to return."}},"description":"Request for GrepArtifacts.","required":["pattern"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:grep":{"post":{"summary":"Grep Artifacts (Smith, workspace)","description":"Searches artifact contents using regex pattern matching.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GrepArtifacts` on `/agents/{agent_id}`.","operationId":"SmithGrepArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GrepArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceGrepArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Artifacts Staging Summary (Smith, workspace)

> Gets a summary of staged artifact changes.\
> \
> Returns a lightweight summary of pending changes including counts and\
> change metadata without diff content. Use DiffArtifacts for full diffs.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetArtifactsStagingSummary\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetArtifactsStagingSummaryResponse":{"type":"object","properties":{"staging_enabled":{"type":"boolean","description":"Whether staging is enabled for any stores."},"changes":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1StagedChange"},"description":"List of staged changes (metadata only, no diff content)."},"total_changes":{"type":"integer","format":"int64","description":"Total number of staged changes."},"additions":{"type":"integer","format":"int64","description":"Number of additions."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions."}},"description":"Response for GetArtifactsStagingSummary."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/artifacts:staging":{"get":{"summary":"Get Artifacts Staging Summary (Smith, workspace)","description":"Gets a summary of staged artifact changes.\n\nReturns a lightweight summary of pending changes including counts and\nchange metadata without diff content. Use DiffArtifacts for full diffs.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetArtifactsStagingSummary` on `/agents/{agent_id}`.","operationId":"SmithGetArtifactsStagingSummary","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetArtifactsStagingSummaryResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"prefix","description":"Optional. Store prefix to limit summary scope (e.g., \"workspace://\").\nIf not specified, returns summary for all stores.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Context (Smith, workspace)

> Gets thread context information including all context items with token counts.\
> \
> Returns a unified view of all items contributing to the context window:\
> \- Memory blocks (fixed and volatile)\
> \- Enabled tools (fixed)\
> \- Conversation history (compactable)\
> \
> Each item includes its token count for context budget management.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetThreadContext\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetThreadContextResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ContextItem"},"description":"List of context items contributing to the thread's context window.","readOnly":true},"model_info":{"$ref":"#/components/schemas/agentsV1ModelInfo"},"summary":{"$ref":"#/components/schemas/agentsV1ContextSummary"},"auto_compact_tokens":{"type":"integer","format":"int64","description":"Prompt token count at which the next completed turn triggers\nauto-compaction.\n\nAbsent when no compactor is configured, in which case auto-compaction\nnever fires, or when the model does not report a context window.","readOnly":true}},"description":"Response containing thread context information."},"agentsV1ContextItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the context item.","readOnly":true},"label":{"type":"string","description":"Human-readable label for display.","readOnly":true},"token_count":{"type":"integer","format":"int64","description":"Number of tokens this item consumes.","readOnly":true},"category":{"$ref":"#/components/schemas/agentsV1ContextCategory"},"memory_block":{"$ref":"#/components/schemas/agentsV1MemoryBlockRef"},"tool":{"$ref":"#/components/schemas/agentsV1ToolRef"}},"description":"A single item contributing to the thread's context window."},"agentsV1ContextCategory":{"type":"string","enum":["CONTEXT_CATEGORY_UNSPECIFIED","CONTEXT_CATEGORY_FIXED","CONTEXT_CATEGORY_VOLATILE","CONTEXT_CATEGORY_COMPACTABLE"],"default":"CONTEXT_CATEGORY_UNSPECIFIED","description":"Category of context items for token budget management.\n\n - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category.\n - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools).\n - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks).\n - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history)."},"agentsV1MemoryBlockRef":{"type":"object","properties":{"block_id":{"type":"string","description":"The unique block identifier (deterministic hash of block name).","readOnly":true},"type":{"type":"string","description":"The block type (e.g., \"text\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the block type.","readOnly":true},"description":{"type":"string","description":"Description of the memory block.","readOnly":true},"scope":{"$ref":"#/components/schemas/agentsV1ScopeLevel"},"mutable":{"type":"boolean","description":"Whether the block is mutable.","readOnly":true}},"description":"Lightweight memory block reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits content and config to keep responses lightweight."},"agentsV1ScopeLevel":{"type":"string","enum":["SCOPE_LEVEL_UNSPECIFIED","SCOPE_LEVEL_AGENT","SCOPE_LEVEL_THREAD","SCOPE_LEVEL_USER"],"default":"SCOPE_LEVEL_UNSPECIFIED","description":"The scope level for a memory block's content storage.\n\n - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT).\n - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads.\n - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content.\n - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content,\nwhich follows them across all of their threads with the agent and is\ninvisible to other users. Only kinds whose allowed_scopes include it\n(or list no restriction) accept it."},"agentsV1ToolRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool identifier (hash of the original tool name).","readOnly":true},"name":{"type":"string","description":"The tool name (may be adapted name if adapters are applied).","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted.","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations).","readOnly":true}},"description":"Lightweight tool reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits parameters_schema to keep responses lightweight."},"agentsV1ModelInfo":{"type":"object","properties":{"model_id":{"type":"string","description":"Model identifier (e.g., \"gpt-4o\", \"claude-3-opus\").","readOnly":true},"max_context_tokens":{"type":"integer","format":"int64","description":"Maximum context length in tokens.","readOnly":true},"max_output_tokens":{"type":"integer","format":"int64","description":"Maximum output tokens.","readOnly":true},"supports_vision":{"type":"boolean","description":"Whether the model supports vision/images.","readOnly":true},"supports_tools":{"type":"boolean","description":"Whether the model supports tool/function calling.","readOnly":true},"supports_structured_output":{"type":"boolean","description":"Whether the model supports structured output (JSON mode).","readOnly":true},"supports_streaming":{"type":"boolean","description":"Whether the model supports streaming responses.","readOnly":true},"supports_reasoning":{"type":"boolean","description":"Whether the model supports reasoning (chain-of-thought).","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"GPT-4o\", \"Claude Sonnet 4.5\").","readOnly":true},"family":{"type":"string","description":"Model family grouping (e.g., \"gpt-4o\", \"claude-4.5\", \"qwen2\").","readOnly":true},"license":{"type":"string","description":"License information (e.g., for open-weight models).","readOnly":true},"parameter_count":{"type":"string","format":"uint64","description":"Number of model parameters.","readOnly":true},"quantization":{"type":"string","description":"Quantization level (e.g., \"Q4_K_M\", \"Q8_0\").","readOnly":true},"supports_documents":{"type":"boolean","description":"Whether the model supports document inputs (PDFs, text files).","readOnly":true},"max_inline_artifact_bytes":{"type":"string","format":"uint64","description":"Maximum size of a single tool result that can be inlined into a\ngeneration request, in raw bytes. Already accounts for base64 expansion\nand a safety margin for request overhead.","readOnly":true},"deprecated":{"type":"boolean","description":"Whether the model is deprecated: still usable, but slated for retirement.","readOnly":true},"retired":{"type":"boolean","description":"Whether the model is retired: loadable (so existing threads/agents don't\nbreak) but generation is refused.","readOnly":true},"replacement_model":{"type":"string","description":"Recommended replacement model id when deprecated or retired.","readOnly":true},"pricing":{"$ref":"#/components/schemas/agentsV1ModelPricing"}},"description":"Information about a model and its capabilities."},"agentsV1ModelPricing":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DatedRates"},"description":"Effective-dated rate rows. Windows should not overlap; if they do, the\nearliest-starting matching row wins so the outcome is deterministic.","readOnly":true}},"description":"Complete pricing knowledge for one model: its effective-dated rate rows.\n\nAn empty `rows` list is a valid \"priced at zero\" card for local models —\ndistinct from a model carrying no `ModelPricing` at all, which means its\ncost is unknown, not free."},"agentsV1DatedRates":{"type":"object","properties":{"effective_from":{"type":"string","format":"date-time","description":"Inclusive start of this row's validity. Absent = open-ended past.","readOnly":true},"effective_until":{"type":"string","format":"date-time","description":"Exclusive end of this row's validity. Absent = open-ended future.","readOnly":true},"base":{"$ref":"#/components/schemas/agentsV1RateCard"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1TierRates"},"description":"Long-context tiers: token-threshold bands above `base`, ascending by\n`threshold_tokens`. Empty = flat pricing. A request's total prompt size\nselects the highest tier whose threshold it reaches, or `base` below\nevery threshold.","readOnly":true}},"description":"One effective-dated pricing row: the rates in force during a validity\nwindow. A model whose price changes on a schedule carries several rows\ndiffering only in rates and effective bounds."},"agentsV1RateCard":{"type":"object","properties":{"input_per_mtok":{"type":"number","format":"double","description":"Fresh (uncached) input, USD per million tokens.","readOnly":true},"output_per_mtok":{"type":"number","format":"double","description":"Output, USD per million tokens. Includes reasoning/thinking tokens.","readOnly":true},"cache_read_per_mtok":{"type":"number","format":"double","description":"Tokens served from cache, USD per million tokens.","readOnly":true},"cache_write_per_mtok":{"type":"number","format":"double","description":"Cache writes at any TTL, USD per million tokens — for providers with a\nsingle write rate regardless of TTL.","readOnly":true},"cache_write_by_ttl":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWriteRate"},"description":"Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`.","readOnly":true}},"description":"One complete set of USD-per-million-token rates. A missing cache rate is\nnot zero — it means the dimension is unpublished, and cost computation\nfalls back loudly (billed at the fresh-input rate, flagged estimated)."},"agentsV1CacheWriteRate":{"type":"object","properties":{"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket,\n3600 for a 1-hour bucket).","readOnly":true},"per_mtok":{"type":"number","format":"double","description":"USD per million tokens written into this bucket.","readOnly":true}},"description":"USD rate for cache writes at one specific TTL bucket."},"agentsV1TierRates":{"type":"object","properties":{"threshold_tokens":{"type":"integer","format":"int64","description":"Prompt-size threshold (total prompt tokens: fresh + cache read + cache\nwrite) at which these rates activate.","readOnly":true},"card":{"$ref":"#/components/schemas/agentsV1RateCard"}},"description":"One long-context tier band: requests whose total prompt tokens meet or\nexceed `threshold_tokens` (and fall below the next tier's threshold, when\none exists) bill the entire request — every class, input and output — at\n`card` instead of the base card."},"agentsV1ContextSummary":{"type":"object","properties":{"fixed_tokens":{"type":"integer","format":"int64","description":"Tokens used by fixed context (immutable memory + tools).","readOnly":true},"volatile_tokens":{"type":"integer","format":"int64","description":"Tokens used by volatile context (mutable memory).","readOnly":true},"compactable_tokens":{"type":"integer","format":"int64","description":"Tokens used by compactable context (conversation).","readOnly":true},"total_used_tokens":{"type":"integer","format":"int64","description":"Total tokens currently in use.","readOnly":true},"available_tokens":{"type":"integer","format":"int64","description":"Tokens available before hitting the context limit.","readOnly":true}},"description":"Summary of token usage by category."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/context":{"get":{"summary":"Get Thread Context (Smith, workspace)","description":"Gets thread context information including all context items with token counts.\n\nReturns a unified view of all items contributing to the context window:\n- Memory blocks (fixed and volatile)\n- Enabled tools (fixed)\n- Conversation history (compactable)\n\nEach item includes its token count for context budget management.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`.","operationId":"SmithGetThreadContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetThreadContextResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"The thread ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events (Smith, workspace)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Smith, workspace)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"SmithGetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message And Wait (Smith, workspace)

> Sends a message and streams back response events synchronously.\
> \
> This RPC adds user input to the specified thread and returns a stream\
> of events representing the assistant's response. Events include output text,\
> tool calls, and completion metadata.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`SendMessageAndWait\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageSyncBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message and stream response events synchronously."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/events":{"post":{"summary":"Send Message And Wait (Smith, workspace)","description":"Sends a message and streams back response events synchronously.\n\nThis RPC adds user input to the specified thread and returns a stream\nof events representing the assistant's response. Events include output text,\ntool calls, and completion metadata.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`.","operationId":"SmithSendMessageAndWait","responses":{"200":{"description":"A successful response.(streaming responses)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/agentsV1Event"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"Stream result of v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageSyncBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Set Thread Feedback (Smith, workspace)

> Sets feedback (like/dislike) for a generation response.\
> \
> Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\
> Setting the same feedback that already exists is a no-op.\
> Use FEEDBACK\_TYPE\_UNSPECIFIED to clear existing feedback.\
> \
> Feedback is stored with the thread and is purely for analytics/UI purposes.\
> It is not visible to the LLM.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`SetThreadFeedback\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SetFeedbackResponse":{"type":"object","properties":{"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"previous_feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Response for setting feedback on a generation."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSetFeedbackBody":{"type":"object","properties":{"generation_id":{"type":"string","description":"Required. The generation ID (from GenerationComplete.id)."},"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Request to set feedback for a generation response."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/feedback":{"post":{"summary":"Set Thread Feedback (Smith, workspace)","description":"Sets feedback (like/dislike) for a generation response.\n\nFeedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\nSetting the same feedback that already exists is a no-op.\nUse FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback.\n\nFeedback is stored with the thread and is purely for analytics/UI purposes.\nIt is not visible to the LLM.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`.","operationId":"SmithSetThreadFeedback","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SetFeedbackResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread containing the generation.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSetFeedbackBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Message (Smith, workspace)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/input":{"post":{"summary":"Send Message (Smith, workspace)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"SmithSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Active Plan (Smith, workspace)

> Gets the active plan snapshot for a thread (with per-step\
> statuses). Distinct from \`GET /plan\`, which returns the template.\
> \
> Returns NOT\_FOUND if no active plan exists.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`GetActivePlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active":{"get":{"summary":"Get Active Plan (Smith, workspace)","description":"Gets the active plan snapshot for a thread (with per-step\nstatuses). Distinct from `GET /plan`, which returns the template.\n\nReturns NOT_FOUND if no active plan exists.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `GetActivePlan` on `/agents/{agent_id}`.","operationId":"SmithGetActivePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to get the plan for.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Mark Plan Step (Smith, workspace)

> Marks a step on the active plan as completed or failed.\
> \
> Returns NOT\_FOUND if no active plan exists or the phase/step index\
> is invalid.\
> Returns FAILED\_PRECONDITION if the thread is currently generating,\
> the step is not in the active phase, or the step is already\
> resolved.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`MarkPlanStep\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceMarkStepBody":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Optional reason for failure (only used when status is STEP_STATUS_FAILED)."}},"description":"Request to mark a step's status in a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active/phases/{phase_index}/steps/{step_index}:mark":{"post":{"summary":"Mark Plan Step (Smith, workspace)","description":"Marks a step on the active plan as completed or failed.\n\nReturns NOT_FOUND if no active plan exists or the phase/step index\nis invalid.\nReturns FAILED_PRECONDITION if the thread is currently generating,\nthe step is not in the active phase, or the step is already\nresolved.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `MarkPlanStep` on `/agents/{agent_id}`.","operationId":"SmithMarkPlanStep","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to modify.","in":"path","required":true,"schema":{"type":"string"}},{"name":"phase_index","description":"Required. 1-indexed phase position.","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"step_index","description":"Required. 1-indexed step position.","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceMarkStepBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Deactivate Plan (Smith, workspace)

> Deactivates the active plan. The snapshot is kept (flagged\
> inactive) for status carry-over on the next activation.\
> \
> No generation guard — always allowed.\
> Returns NOT\_FOUND if no active plan exists.\
> Returns FAILED\_PRECONDITION if the plan is not active.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`DeactivatePlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDeactivatePlanBody":{"type":"object","properties":{},"description":"Request to deactivate a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active:deactivate":{"post":{"summary":"Deactivate Plan (Smith, workspace)","description":"Deactivates the active plan. The snapshot is kept (flagged\ninactive) for status carry-over on the next activation.\n\nNo generation guard — always allowed.\nReturns NOT_FOUND if no active plan exists.\nReturns FAILED_PRECONDITION if the plan is not active.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `DeactivatePlan` on `/agents/{agent_id}`.","operationId":"SmithDeactivatePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to deactivate.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDeactivatePlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Reset Plan (Smith, workspace)

> Resets all step statuses on the active plan back to pending.\
> \
> Clears all step statuses and failure reasons. If the plan is\
> active, it is deactivated first before resetting.\
> Returns NOT\_FOUND if no active plan exists.\
> Returns FAILED\_PRECONDITION if the thread is currently generating.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`ResetPlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceResetPlanBody":{"type":"object","properties":{},"description":"Request to reset all steps in a thread's plan back to pending."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan/active:reset":{"post":{"summary":"Reset Plan (Smith, workspace)","description":"Resets all step statuses on the active plan back to pending.\n\nClears all step statuses and failure reasons. If the plan is\nactive, it is deactivated first before resetting.\nReturns NOT_FOUND if no active plan exists.\nReturns FAILED_PRECONDITION if the thread is currently generating.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `ResetPlan` on `/agents/{agent_id}`.","operationId":"SmithResetPlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to reset.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceResetPlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Activate Plan (Smith, workspace)

> Activates the plan for a thread. Snapshots the current template\
> plan and carries over statuses from any previous snapshot by id.\
> \
> Returns NOT\_FOUND if no plan template exists.\
> Returns FAILED\_PRECONDITION if the thread is currently generating,\
> the plan is already active, or the template has no phases.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`ActivatePlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceActivatePlanBody":{"type":"object","properties":{},"description":"Request to activate a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/plan:activate":{"post":{"summary":"Activate Plan (Smith, workspace)","description":"Activates the plan for a thread. Snapshots the current template\nplan and carries over statuses from any previous snapshot by id.\n\nReturns NOT_FOUND if no plan template exists.\nReturns FAILED_PRECONDITION if the thread is currently generating,\nthe plan is already active, or the template has no phases.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `ActivatePlan` on `/agents/{agent_id}`.","operationId":"SmithActivatePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to activate.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceActivatePlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Smith, workspace)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Smith, workspace)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"SmithStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## List Sub Agents (Smith, workspace)

> Lists sub-agents configured for a thread.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`ListSubAgents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListSubAgentsResponse":{"type":"object","properties":{"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"The sub-agents configured for the thread."},"is_customized":{"type":"boolean","description":"Whether this represents a per-thread customization (vs inherited from agent)."}},"description":"Response message for ListSubAgents."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/sub-agents":{"get":{"summary":"List Sub Agents (Smith, workspace)","description":"Lists sub-agents configured for a thread.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`.","operationId":"SmithListSubAgents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListSubAgentsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread whose sub-agents to list.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Tool Call (Smith, workspace)

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`SendToolCall\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call (Smith, workspace)","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `SendToolCall` on `/agents/{agent_id}`.","operationId":"SmithSendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result (Smith, workspace)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Smith, workspace)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"SmithSendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File (Smith, workspace)

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`UploadThreadFile\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File (Smith, workspace)","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`.","operationId":"SmithUploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Compact Thread (Smith, workspace)

> Starts context compaction for a thread.\
> \
> Compaction summarizes conversation history to reduce context size while\
> preserving essential information. This RPC emits a CompactStart event\
> and returns the compact\_id for tracking.\
> \
> The actual compaction is performed asynchronously. Once complete, a\
> CompactComplete event with the summary content should be added to the\
> thread using the returned compact\_id.\
> \
> While compaction is in progress (CompactStart without CompactComplete),\
> the UI should block user input.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`CompactThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StartCompactionResponse":{"type":"object","properties":{"compact_id":{"type":"string","description":"The unique ID assigned to this compaction operation."}},"description":"Response for starting context compaction."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStartCompactionBody":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"Optional. The event ID from which to start compaction.\nEvents from this ID onwards (inclusive) will be compacted.\nIf not specified, the entire conversation is compacted."}},"description":"Request to start context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. A CompactStart event is emitted immediately,\nand an external compaction process should later emit CompactComplete with the\nsummary."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:compact":{"post":{"summary":"Compact Thread (Smith, workspace)","description":"Starts context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. This RPC emits a CompactStart event\nand returns the compact_id for tracking.\n\nThe actual compaction is performed asynchronously. Once complete, a\nCompactComplete event with the summary content should be added to the\nthread using the returned compact_id.\n\nWhile compaction is in progress (CompactStart without CompactComplete),\nthe UI should block user input.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `CompactThread` on `/agents/{agent_id}`.","operationId":"SmithCompactThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StartCompactionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to compact.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStartCompactionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Fork Thread (Smith, workspace)

> Forks (duplicates) a thread with all its data.\
> \
> Creates a new thread that is a complete copy of the source thread,\
> including events, feedback, memory customizations, scratchpad, plan,\
> and template config customizations.\
> Returns FAILED\_PRECONDITION if the source thread is currently generating.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`ForkThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceForkThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the new thread. Defaults to \"Fork of {source_title}\"."}},"description":"Request message for ForkThread (duplicate a thread with all its data)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:fork":{"post":{"summary":"Fork Thread (Smith, workspace)","description":"Forks (duplicates) a thread with all its data.\n\nCreates a new thread that is a complete copy of the source thread,\nincluding events, feedback, memory customizations, scratchpad, plan,\nand template config customizations.\nReturns FAILED_PRECONDITION if the source thread is currently generating.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `ForkThread` on `/agents/{agent_id}`.","operationId":"SmithForkThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The source thread to fork.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceForkThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stop Thread (Smith, workspace)

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`StopThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread (Smith, workspace)","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `StopThread` on `/agents/{agent_id}`.","operationId":"SmithStopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread (Smith, workspace)

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.\
> \
> Targets the built-in \`smith\` agent in the workspace scope; the generic form is \`WakeThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/smith/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread (Smith, workspace)","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.\n\nTargets the built-in `smith` agent in the workspace scope; the generic form is `WakeThread` on `/agents/{agent_id}`.","operationId":"SmithWakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Agent

> Gets an agent's metadata.\
> \
> Returns the agent's ID and display name.\
> Use other service methods to get detailed information like memory blocks.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetAgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"The agent's unique identifier."},"name":{"type":"string","description":"The agent's display name."},"variables":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1VariableDefinition"},"description":"Variable definitions for thread-scoped configuration.\nVariables can be referenced in any config using `$varName` syntax."},"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"Sub-agents configured for this agent."},"description":{"type":"string","description":"Optional description of the agent's purpose."},"version":{"type":"string","format":"uint64","description":"The version number of the returned agent. When loaded by tag or version,\nthis is the resolved version. When loaded as latest, this is the latest version."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags applied to the returned version."},"auto_title_enabled":{"type":"boolean","description":"Whether the agent automatically generates a title and description for\neach new thread on the first user message."},"customization_explainer_enabled":{"type":"boolean","description":"Whether the agent generates a plain-English summary every time a\nthread's customization changes. The summaries are surfaced in the\ncustomization badge tooltip."},"abilities":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Ability"},"description":"The agent's abilities, as shown on the agent card."},"icon":{"type":"string","description":"The agent's effective icon, as a kebab-case Lucide icon name. Empty\nwhen the agent has no icon."}},"description":"Response message for GetAgent."},"agentsV1VariableDefinition":{"type":"object","properties":{"name":{"type":"string","description":"The variable name (used as `$name` in configs)."},"required":{"type":"boolean","description":"Whether this variable is required when creating a thread."},"default":{"type":"string","description":"Default value if not provided (only valid for non-required variables)."},"description":{"type":"string","description":"Human-readable description of what this variable is for."},"segment":{"type":"string","description":"URL path segment name for multi-tenant parent path routing.\nWhen set, this variable can be extracted from a parent path like\n`/organizations/acme/workspaces/dev` where `organizations` and `workspaces`\nare segment names. If not set, the variable `name` is used as the segment."},"fixed_value":{"type":"string","description":"Fixed value for this variable.\nWhen set, the variable is locked to this value and cannot be overridden.\nUnlike `default` (which can be overridden), a fixed value is immutable."}},"description":"Defines a variable that can be used in agent configuration.\n\nVariables are defined at the agent level and filled when creating a thread.\nThey can be referenced in any configuration value using `$varName` syntax."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"agentsV1Ability":{"type":"object","properties":{"name":{"type":"string","description":"Short label, e.g. \"web search\", \"PDF editing\", \"team memory\"."},"icon":{"type":"string","description":"Icon identifier, as a kebab-case Lucide icon name (e.g. \"file-text\",\n\"git-branch\", \"map-pin\")."},"description":{"type":"string","description":"Optional one-line description for a tooltip."}},"description":"A single human-readable agent capability shown on the agent card."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}":{"get":{"summary":"Get Agent","description":"Gets an agent's metadata.\n\nReturns the agent's ID and display name.\nUse other service methods to get detailed information like memory blocks.","operationId":"GetAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent to get.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Agent

> Deletes an agent from both memory and disk.\
> \
> This removes the agent completely. The operation cannot be undone.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}":{"delete":{"summary":"Delete Agent","description":"Deletes an agent from both memory and disk.\n\nThis removes the agent completely. The operation cannot be undone.","operationId":"DeleteAgent","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Agent

> Updates an agent's metadata.\
> \
> Supports updating the display name and the label set.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1UpdateAgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"The agent's unique identifier."},"name":{"type":"string","description":"The updated display name."},"description":{"type":"string","description":"The updated description."},"version":{"type":"string","format":"uint64","description":"The new version number, if a new version was created. None if the\ntemplate was identical to the current latest version."},"labels":{"type":"array","items":{"type":"string"},"description":"The agent's labels after the update, normalised: trimmed, de-duplicated,\nand re-cased to match any spelling already in use elsewhere. Always\npopulated, whether or not the request carried labels, so a client can\nsee what its input resolved to."}},"description":"Response message for UpdateAgent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsAgentServiceUpdateAgentBody":{"type":"object","properties":{"name":{"type":"string","description":"The new display name for the agent."},"labels":{"$ref":"#/components/schemas/agentsV1AgentLabels"}},"description":"Request to edit an agent's own identity.\n\nRenaming and relabelling are the only direct edits to a base agent — its\ndescription, abilities, and feature toggles are deployable configuration,\nedited on a thread and promoted by Deploy, never written here."},"agentsV1AgentLabels":{"type":"object","properties":{"values":{"type":"array","items":{"type":"string"},"description":"The full desired label set. Empty means the agent has no labels."}},"description":"A complete set of agent labels, used where a caller replaces the whole set\nrather than adding or removing individual entries.\n\nThis exists so an update can distinguish \"leave the labels alone\" from\n\"remove every label\": a bare `repeated string` field has no presence, so\nboth would arrive as an empty list. Wrapped in a message, absence and an\nempty `values` are separate signals."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}":{"patch":{"summary":"Update Agent","description":"Updates an agent's metadata.\n\nSupports updating the display name and the label set.","operationId":"UpdateAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1UpdateAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsAgentServiceUpdateAgentBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Agent Version By Tag

> Fetches a specific version of an agent's full configuration by tag name.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetAgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"The agent's unique identifier."},"name":{"type":"string","description":"The agent's display name."},"variables":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1VariableDefinition"},"description":"Variable definitions for thread-scoped configuration.\nVariables can be referenced in any config using `$varName` syntax."},"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"Sub-agents configured for this agent."},"description":{"type":"string","description":"Optional description of the agent's purpose."},"version":{"type":"string","format":"uint64","description":"The version number of the returned agent. When loaded by tag or version,\nthis is the resolved version. When loaded as latest, this is the latest version."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags applied to the returned version."},"auto_title_enabled":{"type":"boolean","description":"Whether the agent automatically generates a title and description for\neach new thread on the first user message."},"customization_explainer_enabled":{"type":"boolean","description":"Whether the agent generates a plain-English summary every time a\nthread's customization changes. The summaries are surfaced in the\ncustomization badge tooltip."},"abilities":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Ability"},"description":"The agent's abilities, as shown on the agent card."},"icon":{"type":"string","description":"The agent's effective icon, as a kebab-case Lucide icon name. Empty\nwhen the agent has no icon."}},"description":"Response message for GetAgent."},"agentsV1VariableDefinition":{"type":"object","properties":{"name":{"type":"string","description":"The variable name (used as `$name` in configs)."},"required":{"type":"boolean","description":"Whether this variable is required when creating a thread."},"default":{"type":"string","description":"Default value if not provided (only valid for non-required variables)."},"description":{"type":"string","description":"Human-readable description of what this variable is for."},"segment":{"type":"string","description":"URL path segment name for multi-tenant parent path routing.\nWhen set, this variable can be extracted from a parent path like\n`/organizations/acme/workspaces/dev` where `organizations` and `workspaces`\nare segment names. If not set, the variable `name` is used as the segment."},"fixed_value":{"type":"string","description":"Fixed value for this variable.\nWhen set, the variable is locked to this value and cannot be overridden.\nUnlike `default` (which can be overridden), a fixed value is immutable."}},"description":"Defines a variable that can be used in agent configuration.\n\nVariables are defined at the agent level and filled when creating a thread.\nThey can be referenced in any configuration value using `$varName` syntax."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"agentsV1Ability":{"type":"object","properties":{"name":{"type":"string","description":"Short label, e.g. \"web search\", \"PDF editing\", \"team memory\"."},"icon":{"type":"string","description":"Icon identifier, as a kebab-case Lucide icon name (e.g. \"file-text\",\n\"git-branch\", \"map-pin\")."},"description":{"type":"string","description":"Optional one-line description for a tooltip."}},"description":"A single human-readable agent capability shown on the agent card."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/tags/{tag}":{"get":{"summary":"Get Agent Version By Tag","description":"Fetches a specific version of an agent's full configuration by tag name.","operationId":"GetAgentVersionByTag","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"tag","description":"Required. The tag name resolving to a version.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Untag Agent Version

> Removes a tag from an agent.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/tags/{tag}":{"delete":{"summary":"Untag Agent Version","description":"Removes a tag from an agent.","operationId":"UntagAgentVersion","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"tag","description":"The tag name to remove.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## List Threads

> Lists all threads for an agent.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads":{"get":{"summary":"List Threads","description":"Lists all threads for an agent.","operationId":"ListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent whose threads to list.","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads":{"post":{"summary":"Create Thread","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.","operationId":"CreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent to create the thread for.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete All Threads

> Deletes all threads for an agent.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads":{"delete":{"summary":"Delete All Threads","description":"Deletes all threads for an agent.","operationId":"DeleteAllThreads","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent whose threads to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread

> Gets a thread by ID.\
> \
> Returns thread metadata and event count without loading the full event history.\
> Returns NOT\_FOUND if the thread doesn't exist.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}":{"get":{"summary":"Get Thread","description":"Gets a thread by ID.\n\nReturns thread metadata and event count without loading the full event history.\nReturns NOT_FOUND if the thread doesn't exist.","operationId":"GetThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Thread

> Deletes a thread and all its events.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}":{"delete":{"summary":"Delete Thread","description":"Deletes a thread and all its events.","operationId":"DeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Thread

> Updates a thread's title and/or description.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional new title for the thread."},"description":{"type":"string","description":"Optional new description for the thread."}},"description":"Request to update a thread's metadata."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}":{"patch":{"summary":"Update Thread","description":"Updates a thread's title and/or description.","operationId":"UpdateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Artifacts

> Lists artifacts with optional filters.\
> Supports S3-style delimiter for folder navigation.\
> Thread ID is required for variable-scoped artifact access.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListArtifactsResponse":{"type":"object","properties":{"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Artifact"},"description":"Artifacts matching the filter."},"common_prefixes":{"type":"array","items":{"type":"string"},"description":"Common prefixes (\"folders\") when delimiter is set."}},"description":"Response for ListArtifacts."},"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts":{"get":{"summary":"List Artifacts","description":"Lists artifacts with optional filters.\nSupports S3-style delimiter for folder navigation.\nThread ID is required for variable-scoped artifact access.","operationId":"ListArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"prefix","description":"Optional. Filter by URI prefix (e.g., \"workspace://src/\").\nIf not specified, lists from all stores.","in":"query","required":false,"schema":{"type":"string"}},{"name":"delimiter","description":"Optional. Delimiter for S3-style folder grouping (typically \"/\").","in":"query","required":false,"schema":{"type":"string"}},{"name":"mime_type","description":"Optional. Filter by MIME type prefix (e.g., \"text/\", \"image/\").","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","description":"Optional. Maximum number of results.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}}],"tags":["Agents"]}}}}
```

## Get Artifact

> Gets artifact metadata by URI.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}":{"get":{"summary":"Get Artifact","description":"Gets artifact metadata by URI.","operationId":"GetArtifact","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Artifact"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Artifact

> Creates or updates an artifact.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateArtifactBody":{"type":"object","properties":{"mime_type":{"type":"string","description":"Required. The MIME type."},"data":{"type":"string","format":"byte","description":"Required. The artifact content."},"description":{"type":"string","description":"Optional description."}},"description":"Request for UpdateArtifact.","required":["mime_type","data"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}":{"put":{"summary":"Update Artifact","description":"Creates or updates an artifact.","operationId":"UpdateArtifact","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Artifact"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateArtifactBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete Artifact

> Deletes an artifact by URI.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}":{"delete":{"summary":"Delete Artifact","description":"Deletes an artifact by URI.","operationId":"DeleteArtifact","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Artifact Content

> Gets artifact content by URI.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ArtifactContentResponse":{"type":"object","properties":{"artifact":{"$ref":"#/components/schemas/agentsV1Artifact"},"data":{"type":"string","format":"byte","description":"The raw content bytes."}},"description":"Response for GetArtifactContent."},"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}:content":{"get":{"summary":"Get Artifact Content","description":"Gets artifact content by URI.","operationId":"GetArtifactContent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ArtifactContentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Artifact Diff

> Gets the diff for a single staged artifact.\
> \
> Returns the unified diff for a specific artifact if it has staged changes.\
> Returns empty diff for binary files or if no changes exist.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetArtifactDiffResponse":{"type":"object","properties":{"has_changes":{"type":"boolean","description":"Whether this artifact has staged changes."},"change":{"$ref":"#/components/schemas/agentsV1StagedChange"},"diff":{"type":"string","description":"Unified diff content.\nEmpty for binary files, deleted artifacts, or if no changes."}},"description":"Response for GetArtifactDiff."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}:diff":{"get":{"summary":"Get Artifact Diff","description":"Gets the diff for a single staged artifact.\n\nReturns the unified diff for a specific artifact if it has staged changes.\nReturns empty diff for binary files or if no changes exist.","operationId":"GetArtifactDiff","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetArtifactDiffResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Artifact Thumbnail

> Fetch a server-rendered thumbnail of an artifact\
> \
> Returns a rendered preview image for the artifact at\
> \`artifact\_uri\`. The first request renders the image; subsequent\
> requests for identical artifact bytes serve from a thread-scoped\
> cache.\
> \
> Returns \`404\` when the artifact does not exist or the file\
> type has no preview support — clients should fall back to a\
> generic file-type icon.\
> \
> Returns \`500\` when rendering failed.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts/{artifact_uri}:thumbnail":{"get":{"summary":"Get Artifact Thumbnail","description":"Fetch a server-rendered thumbnail of an artifact\n\nReturns a rendered preview image for the artifact at\n`artifact_uri`. The first request renders the image; subsequent\nrequests for identical artifact bytes serve from a thread-scoped\ncache.\n\nReturns `404` when the artifact does not exist or the file\ntype has no preview support — clients should fall back to a\ngeneric file-type icon.\n\nReturns `500` when rendering failed.","operationId":"GetArtifactThumbnail","responses":{"200":{"description":"Rendered thumbnail bytes.","headers":{"ETag":{"description":"Strong validator derived from `sha256(artifact bytes) + size`.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=31536000, immutable` since thumbnails are content-addressed.","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Cached body matches `If-None-Match` — no body returned."},"400":{"description":"Invalid `size` parameter."},"404":{"description":"Artifact missing or file type has no preview support — client should fall back to a generic icon."},"500":{"description":"Thumbnail render or store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","description":"The ID of the agent that owns the thread.","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the artifact belongs to.","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","in":"path","description":"The artifact URI (e.g. `uploads://report.pdf`,\n`workspace://src/main.rs`). Must be URL-encoded so the `://`\nand any embedded slashes survive routing as a single path\nsegment.\n Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","required":true,"schema":{"type":"string"}},{"name":"size","in":"query","description":"Logical size bucket — `small` (~140 px) or `medium` (~320 px). Defaults to `small`.","required":false,"schema":{"type":"string","enum":["small","medium"],"default":"small"}},{"name":"If-None-Match","in":"header","description":"Conditional GET. When the ETag matches the cached thumbnail, the server responds `304 Not Modified` with no body.","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Commit Artifacts

> Commits staged artifact changes to the underlying store.\
> \
> Persists all staged changes (additions, modifications, deletions) to\
> the underlying store. For stores without staging, this is a no-op.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1CommitArtifactsResponse":{"type":"object","properties":{"committed_count":{"type":"integer","format":"int64","description":"Number of artifacts committed."},"additions":{"type":"integer","format":"int64","description":"Number of additions committed."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications committed."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions committed."},"version":{"type":"string","description":"New artifact version produced by this commit, if the store versions its\ncontents. Absent for stores without a version concept."}},"description":"Response for CommitArtifacts."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCommitArtifactsBody":{"type":"object","properties":{"prefix":{"type":"string","description":"Optional. Store prefix to limit commit scope (e.g., \"workspace://\").\nIf not specified, commits all staged changes across all stores."}},"description":"Request for CommitArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:commit":{"post":{"summary":"Commit Artifacts","description":"Commits staged artifact changes to the underlying store.\n\nPersists all staged changes (additions, modifications, deletions) to\nthe underlying store. For stores without staging, this is a no-op.","operationId":"CommitArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1CommitArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCommitArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Diff Artifacts

> Gets staged artifact changes with optional diff content.\
> \
> Returns information about artifacts that have been modified but not yet\
> committed. For stores with staging enabled, this shows pending changes.\
> For stores without staging, returns an empty response.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DiffArtifactsResponse":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DiffEntry"},"description":"List of staged changes with optional diff content."},"total_changes":{"type":"integer","format":"int64","description":"Total number of staged changes."},"additions":{"type":"integer","format":"int64","description":"Number of additions."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions."}},"description":"Response for DiffArtifacts."},"agentsV1DiffEntry":{"type":"object","properties":{"change":{"$ref":"#/components/schemas/agentsV1StagedChange"},"diff":{"type":"string","description":"Unified diff content (only if include_content was true).\nEmpty for binary files or deleted artifacts."}},"description":"A diff entry with optional content."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDiffArtifactsBody":{"type":"object","properties":{"prefix":{"type":"string","description":"Optional. Store prefix to limit diff scope (e.g., \"workspace://\").\nIf not specified, returns diff for all stores."},"include_content":{"type":"boolean","description":"Optional. Include unified diff content for each change.\nDefault is false (summary only)."}},"description":"Request for DiffArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:diff":{"post":{"summary":"Diff Artifacts","description":"Gets staged artifact changes with optional diff content.\n\nReturns information about artifacts that have been modified but not yet\ncommitted. For stores with staging enabled, this shows pending changes.\nFor stores without staging, returns an empty response.","operationId":"DiffArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DiffArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDiffArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Discard Artifacts

> Discards all staged artifact changes without committing.\
> \
> Clears all pending changes (additions, modifications, deletions) from\
> the staging area. For stores without staging, this is a no-op.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DiscardArtifactsResponse":{"type":"object","properties":{"discarded_count":{"type":"integer","format":"int64","description":"Number of artifacts discarded."},"additions":{"type":"integer","format":"int64","description":"Number of additions discarded."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications discarded."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions discarded."}},"description":"Response for DiscardArtifacts."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDiscardArtifactsBody":{"type":"object","properties":{},"description":"Request for DiscardArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:discard":{"post":{"summary":"Discard Artifacts","description":"Discards all staged artifact changes without committing.\n\nClears all pending changes (additions, modifications, deletions) from\nthe staging area. For stores without staging, this is a no-op.","operationId":"DiscardArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DiscardArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDiscardArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Grep Artifacts

> Searches artifact contents using regex pattern matching.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GrepArtifactsResponse":{"type":"object","properties":{"pattern":{"type":"string","description":"The pattern that was searched."},"match_count":{"type":"integer","format":"int64","description":"Total number of matches found (may exceed matches size if limited)."},"matches":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1GrepMatch"},"description":"The matches (may be limited by request limit)."}},"description":"Response for GrepArtifacts."},"agentsV1GrepMatch":{"type":"object","properties":{"id":{"type":"string","description":"Artifact ID containing the match.","readOnly":true},"name":{"type":"string","description":"Artifact name/path.","readOnly":true},"line":{"type":"integer","format":"int64","description":"Line number (1-indexed).","readOnly":true},"content":{"type":"string","description":"The matching line content.","readOnly":true},"context_before":{"type":"array","items":{"type":"string"},"description":"Lines before the match (context).","readOnly":true},"context_after":{"type":"array","items":{"type":"string"},"description":"Lines after the match (context).","readOnly":true}},"description":"A single grep match within an artifact."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceGrepArtifactsBody":{"type":"object","properties":{"pattern":{"type":"string","description":"Required. Regex pattern to search for."},"prefix":{"type":"string","description":"Optional. URI prefix to limit search scope (e.g., \"workspace://src/\")."},"glob":{"type":"string","description":"Optional. Glob pattern to filter files (e.g., \"*.rs\")."},"ignore_case":{"type":"boolean","description":"Optional. Case-insensitive search."},"context_lines":{"type":"integer","format":"int64","description":"Optional. Number of context lines before/after each match."},"limit":{"type":"integer","format":"int64","description":"Optional. Maximum number of matches to return."}},"description":"Request for GrepArtifacts.","required":["pattern"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:grep":{"post":{"summary":"Grep Artifacts","description":"Searches artifact contents using regex pattern matching.","operationId":"GrepArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GrepArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceGrepArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Artifacts Staging Summary

> Gets a summary of staged artifact changes.\
> \
> Returns a lightweight summary of pending changes including counts and\
> change metadata without diff content. Use DiffArtifacts for full diffs.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetArtifactsStagingSummaryResponse":{"type":"object","properties":{"staging_enabled":{"type":"boolean","description":"Whether staging is enabled for any stores."},"changes":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1StagedChange"},"description":"List of staged changes (metadata only, no diff content)."},"total_changes":{"type":"integer","format":"int64","description":"Total number of staged changes."},"additions":{"type":"integer","format":"int64","description":"Number of additions."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions."}},"description":"Response for GetArtifactsStagingSummary."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/artifacts:staging":{"get":{"summary":"Get Artifacts Staging Summary","description":"Gets a summary of staged artifact changes.\n\nReturns a lightweight summary of pending changes including counts and\nchange metadata without diff content. Use DiffArtifacts for full diffs.","operationId":"GetArtifactsStagingSummary","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetArtifactsStagingSummaryResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"prefix","description":"Optional. Store prefix to limit summary scope (e.g., \"workspace://\").\nIf not specified, returns summary for all stores.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Context

> Gets thread context information including all context items with token counts.\
> \
> Returns a unified view of all items contributing to the context window:\
> \- Memory blocks (fixed and volatile)\
> \- Enabled tools (fixed)\
> \- Conversation history (compactable)\
> \
> Each item includes its token count for context budget management.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetThreadContextResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ContextItem"},"description":"List of context items contributing to the thread's context window.","readOnly":true},"model_info":{"$ref":"#/components/schemas/agentsV1ModelInfo"},"summary":{"$ref":"#/components/schemas/agentsV1ContextSummary"},"auto_compact_tokens":{"type":"integer","format":"int64","description":"Prompt token count at which the next completed turn triggers\nauto-compaction.\n\nAbsent when no compactor is configured, in which case auto-compaction\nnever fires, or when the model does not report a context window.","readOnly":true}},"description":"Response containing thread context information."},"agentsV1ContextItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the context item.","readOnly":true},"label":{"type":"string","description":"Human-readable label for display.","readOnly":true},"token_count":{"type":"integer","format":"int64","description":"Number of tokens this item consumes.","readOnly":true},"category":{"$ref":"#/components/schemas/agentsV1ContextCategory"},"memory_block":{"$ref":"#/components/schemas/agentsV1MemoryBlockRef"},"tool":{"$ref":"#/components/schemas/agentsV1ToolRef"}},"description":"A single item contributing to the thread's context window."},"agentsV1ContextCategory":{"type":"string","enum":["CONTEXT_CATEGORY_UNSPECIFIED","CONTEXT_CATEGORY_FIXED","CONTEXT_CATEGORY_VOLATILE","CONTEXT_CATEGORY_COMPACTABLE"],"default":"CONTEXT_CATEGORY_UNSPECIFIED","description":"Category of context items for token budget management.\n\n - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category.\n - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools).\n - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks).\n - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history)."},"agentsV1MemoryBlockRef":{"type":"object","properties":{"block_id":{"type":"string","description":"The unique block identifier (deterministic hash of block name).","readOnly":true},"type":{"type":"string","description":"The block type (e.g., \"text\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the block type.","readOnly":true},"description":{"type":"string","description":"Description of the memory block.","readOnly":true},"scope":{"$ref":"#/components/schemas/agentsV1ScopeLevel"},"mutable":{"type":"boolean","description":"Whether the block is mutable.","readOnly":true}},"description":"Lightweight memory block reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits content and config to keep responses lightweight."},"agentsV1ScopeLevel":{"type":"string","enum":["SCOPE_LEVEL_UNSPECIFIED","SCOPE_LEVEL_AGENT","SCOPE_LEVEL_THREAD","SCOPE_LEVEL_USER"],"default":"SCOPE_LEVEL_UNSPECIFIED","description":"The scope level for a memory block's content storage.\n\n - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT).\n - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads.\n - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content.\n - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content,\nwhich follows them across all of their threads with the agent and is\ninvisible to other users. Only kinds whose allowed_scopes include it\n(or list no restriction) accept it."},"agentsV1ToolRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool identifier (hash of the original tool name).","readOnly":true},"name":{"type":"string","description":"The tool name (may be adapted name if adapters are applied).","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted.","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations).","readOnly":true}},"description":"Lightweight tool reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits parameters_schema to keep responses lightweight."},"agentsV1ModelInfo":{"type":"object","properties":{"model_id":{"type":"string","description":"Model identifier (e.g., \"gpt-4o\", \"claude-3-opus\").","readOnly":true},"max_context_tokens":{"type":"integer","format":"int64","description":"Maximum context length in tokens.","readOnly":true},"max_output_tokens":{"type":"integer","format":"int64","description":"Maximum output tokens.","readOnly":true},"supports_vision":{"type":"boolean","description":"Whether the model supports vision/images.","readOnly":true},"supports_tools":{"type":"boolean","description":"Whether the model supports tool/function calling.","readOnly":true},"supports_structured_output":{"type":"boolean","description":"Whether the model supports structured output (JSON mode).","readOnly":true},"supports_streaming":{"type":"boolean","description":"Whether the model supports streaming responses.","readOnly":true},"supports_reasoning":{"type":"boolean","description":"Whether the model supports reasoning (chain-of-thought).","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"GPT-4o\", \"Claude Sonnet 4.5\").","readOnly":true},"family":{"type":"string","description":"Model family grouping (e.g., \"gpt-4o\", \"claude-4.5\", \"qwen2\").","readOnly":true},"license":{"type":"string","description":"License information (e.g., for open-weight models).","readOnly":true},"parameter_count":{"type":"string","format":"uint64","description":"Number of model parameters.","readOnly":true},"quantization":{"type":"string","description":"Quantization level (e.g., \"Q4_K_M\", \"Q8_0\").","readOnly":true},"supports_documents":{"type":"boolean","description":"Whether the model supports document inputs (PDFs, text files).","readOnly":true},"max_inline_artifact_bytes":{"type":"string","format":"uint64","description":"Maximum size of a single tool result that can be inlined into a\ngeneration request, in raw bytes. Already accounts for base64 expansion\nand a safety margin for request overhead.","readOnly":true},"deprecated":{"type":"boolean","description":"Whether the model is deprecated: still usable, but slated for retirement.","readOnly":true},"retired":{"type":"boolean","description":"Whether the model is retired: loadable (so existing threads/agents don't\nbreak) but generation is refused.","readOnly":true},"replacement_model":{"type":"string","description":"Recommended replacement model id when deprecated or retired.","readOnly":true},"pricing":{"$ref":"#/components/schemas/agentsV1ModelPricing"}},"description":"Information about a model and its capabilities."},"agentsV1ModelPricing":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DatedRates"},"description":"Effective-dated rate rows. Windows should not overlap; if they do, the\nearliest-starting matching row wins so the outcome is deterministic.","readOnly":true}},"description":"Complete pricing knowledge for one model: its effective-dated rate rows.\n\nAn empty `rows` list is a valid \"priced at zero\" card for local models —\ndistinct from a model carrying no `ModelPricing` at all, which means its\ncost is unknown, not free."},"agentsV1DatedRates":{"type":"object","properties":{"effective_from":{"type":"string","format":"date-time","description":"Inclusive start of this row's validity. Absent = open-ended past.","readOnly":true},"effective_until":{"type":"string","format":"date-time","description":"Exclusive end of this row's validity. Absent = open-ended future.","readOnly":true},"base":{"$ref":"#/components/schemas/agentsV1RateCard"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1TierRates"},"description":"Long-context tiers: token-threshold bands above `base`, ascending by\n`threshold_tokens`. Empty = flat pricing. A request's total prompt size\nselects the highest tier whose threshold it reaches, or `base` below\nevery threshold.","readOnly":true}},"description":"One effective-dated pricing row: the rates in force during a validity\nwindow. A model whose price changes on a schedule carries several rows\ndiffering only in rates and effective bounds."},"agentsV1RateCard":{"type":"object","properties":{"input_per_mtok":{"type":"number","format":"double","description":"Fresh (uncached) input, USD per million tokens.","readOnly":true},"output_per_mtok":{"type":"number","format":"double","description":"Output, USD per million tokens. Includes reasoning/thinking tokens.","readOnly":true},"cache_read_per_mtok":{"type":"number","format":"double","description":"Tokens served from cache, USD per million tokens.","readOnly":true},"cache_write_per_mtok":{"type":"number","format":"double","description":"Cache writes at any TTL, USD per million tokens — for providers with a\nsingle write rate regardless of TTL.","readOnly":true},"cache_write_by_ttl":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWriteRate"},"description":"Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`.","readOnly":true}},"description":"One complete set of USD-per-million-token rates. A missing cache rate is\nnot zero — it means the dimension is unpublished, and cost computation\nfalls back loudly (billed at the fresh-input rate, flagged estimated)."},"agentsV1CacheWriteRate":{"type":"object","properties":{"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket,\n3600 for a 1-hour bucket).","readOnly":true},"per_mtok":{"type":"number","format":"double","description":"USD per million tokens written into this bucket.","readOnly":true}},"description":"USD rate for cache writes at one specific TTL bucket."},"agentsV1TierRates":{"type":"object","properties":{"threshold_tokens":{"type":"integer","format":"int64","description":"Prompt-size threshold (total prompt tokens: fresh + cache read + cache\nwrite) at which these rates activate.","readOnly":true},"card":{"$ref":"#/components/schemas/agentsV1RateCard"}},"description":"One long-context tier band: requests whose total prompt tokens meet or\nexceed `threshold_tokens` (and fall below the next tier's threshold, when\none exists) bill the entire request — every class, input and output — at\n`card` instead of the base card."},"agentsV1ContextSummary":{"type":"object","properties":{"fixed_tokens":{"type":"integer","format":"int64","description":"Tokens used by fixed context (immutable memory + tools).","readOnly":true},"volatile_tokens":{"type":"integer","format":"int64","description":"Tokens used by volatile context (mutable memory).","readOnly":true},"compactable_tokens":{"type":"integer","format":"int64","description":"Tokens used by compactable context (conversation).","readOnly":true},"total_used_tokens":{"type":"integer","format":"int64","description":"Total tokens currently in use.","readOnly":true},"available_tokens":{"type":"integer","format":"int64","description":"Tokens available before hitting the context limit.","readOnly":true}},"description":"Summary of token usage by category."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/context":{"get":{"summary":"Get Thread Context","description":"Gets thread context information including all context items with token counts.\n\nReturns a unified view of all items contributing to the context window:\n- Memory blocks (fixed and volatile)\n- Enabled tools (fixed)\n- Conversation history (compactable)\n\nEach item includes its token count for context budget management.","operationId":"GetThreadContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetThreadContextResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"The thread ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.","operationId":"GetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message And Wait

> Sends a message and streams back response events synchronously.\
> \
> This RPC adds user input to the specified thread and returns a stream\
> of events representing the assistant's response. Events include output text,\
> tool calls, and completion metadata.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageSyncBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message and stream response events synchronously."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events":{"post":{"summary":"Send Message And Wait","description":"Sends a message and streams back response events synchronously.\n\nThis RPC adds user input to the specified thread and returns a stream\nof events representing the assistant's response. Events include output text,\ntool calls, and completion metadata.","operationId":"SendMessageAndWait","responses":{"200":{"description":"A successful response.(streaming responses)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/agentsV1Event"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"Stream result of v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageSyncBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete Event

> Deletes an event and its entire associated turn from the thread.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DeleteEventResponse":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64"},"to_event_id":{"type":"string","format":"uint64"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDeleteEventBody":{"type":"object","properties":{"event_id":{"type":"string","format":"uint64"}},"description":"Deletes an event and its entire associated turn from the thread.\nThe event_id must refer to an InputText event that starts a turn.\nThis deletes all events in the turn: the initiating InputText, all generation output\n(text, tool calls, tool results, reasoning, interrupts and their answers), and\nterminal events (GenerationComplete/GenerationFailed) through all generation cycles\nuntil the next InputText event.\nReturns INVALID_ARGUMENT if event_id does not refer to an InputText event."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events:delete":{"post":{"summary":"Delete Event","description":"Deletes an event and its entire associated turn from the thread.","operationId":"DeleteEvent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DeleteEventResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDeleteEventBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Reset Events

> Resets all events and feedback in a thread.\
> \
> Clears the entire event history and associated feedback while preserving\
> all other thread state (plan, memory customizations, config customizations, scratchpad).\
> Returns FAILED\_PRECONDITION if the thread is currently generating.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ResetEventsResponse":{"type":"object","description":"Response for ResetEvents."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceResetEventsBody":{"type":"object","properties":{},"description":"Request message for ResetEvents (clear all events and feedback from a thread)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events:reset":{"post":{"summary":"Reset Events","description":"Resets all events and feedback in a thread.\n\nClears the entire event history and associated feedback while preserving\nall other thread state (plan, memory customizations, config customizations, scratchpad).\nReturns FAILED_PRECONDITION if the thread is currently generating.","operationId":"ResetEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ResetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread whose events to reset.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceResetEventsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Restore Event

> Restores a previously deleted event and its entire associated turn.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1RestoreEventResponse":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64"},"to_event_id":{"type":"string","format":"uint64"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceRestoreEventBody":{"type":"object","properties":{"event_id":{"type":"string","format":"uint64"}},"description":"Restores a previously deleted event and its entire associated turn.\nThe event_id must refer to the InputText event that was previously deleted.\nAll events in the turn are restored.\nReturns NOT_FOUND if no deleted turn starts at the given event_id."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/events:restore":{"post":{"summary":"Restore Event","description":"Restores a previously deleted event and its entire associated turn.","operationId":"RestoreEvent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1RestoreEventResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceRestoreEventBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Set Thread Feedback

> Sets feedback (like/dislike) for a generation response.\
> \
> Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\
> Setting the same feedback that already exists is a no-op.\
> Use FEEDBACK\_TYPE\_UNSPECIFIED to clear existing feedback.\
> \
> Feedback is stored with the thread and is purely for analytics/UI purposes.\
> It is not visible to the LLM.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SetFeedbackResponse":{"type":"object","properties":{"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"previous_feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Response for setting feedback on a generation."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSetFeedbackBody":{"type":"object","properties":{"generation_id":{"type":"string","description":"Required. The generation ID (from GenerationComplete.id)."},"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Request to set feedback for a generation response."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/feedback":{"post":{"summary":"Set Thread Feedback","description":"Sets feedback (like/dislike) for a generation response.\n\nFeedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\nSetting the same feedback that already exists is a no-op.\nUse FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback.\n\nFeedback is stored with the thread and is purely for analytics/UI purposes.\nIt is not visible to the LLM.","operationId":"SetThreadFeedback","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SetFeedbackResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread containing the generation.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSetFeedbackBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Message

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/input":{"post":{"summary":"Send Message","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.","operationId":"SendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Active Plan

> Gets the active plan snapshot for a thread (with per-step\
> statuses). Distinct from \`GET /plan\`, which returns the template.\
> \
> Returns NOT\_FOUND if no active plan exists.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active":{"get":{"summary":"Get Active Plan","description":"Gets the active plan snapshot for a thread (with per-step\nstatuses). Distinct from `GET /plan`, which returns the template.\n\nReturns NOT_FOUND if no active plan exists.","operationId":"GetActivePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to get the plan for.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Mark Plan Step

> Marks a step on the active plan as completed or failed.\
> \
> Returns NOT\_FOUND if no active plan exists or the phase/step index\
> is invalid.\
> Returns FAILED\_PRECONDITION if the thread is currently generating,\
> the step is not in the active phase, or the step is already\
> resolved.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceMarkStepBody":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Optional reason for failure (only used when status is STEP_STATUS_FAILED)."}},"description":"Request to mark a step's status in a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active/phases/{phase_index}/steps/{step_index}:mark":{"post":{"summary":"Mark Plan Step","description":"Marks a step on the active plan as completed or failed.\n\nReturns NOT_FOUND if no active plan exists or the phase/step index\nis invalid.\nReturns FAILED_PRECONDITION if the thread is currently generating,\nthe step is not in the active phase, or the step is already\nresolved.","operationId":"MarkPlanStep","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to modify.","in":"path","required":true,"schema":{"type":"string"}},{"name":"phase_index","description":"Required. 1-indexed phase position.","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"step_index","description":"Required. 1-indexed step position.","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceMarkStepBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Deactivate Plan

> Deactivates the active plan. The snapshot is kept (flagged\
> inactive) for status carry-over on the next activation.\
> \
> No generation guard — always allowed.\
> Returns NOT\_FOUND if no active plan exists.\
> Returns FAILED\_PRECONDITION if the plan is not active.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDeactivatePlanBody":{"type":"object","properties":{},"description":"Request to deactivate a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active:deactivate":{"post":{"summary":"Deactivate Plan","description":"Deactivates the active plan. The snapshot is kept (flagged\ninactive) for status carry-over on the next activation.\n\nNo generation guard — always allowed.\nReturns NOT_FOUND if no active plan exists.\nReturns FAILED_PRECONDITION if the plan is not active.","operationId":"DeactivatePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to deactivate.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDeactivatePlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Reset Plan

> Resets all step statuses on the active plan back to pending.\
> \
> Clears all step statuses and failure reasons. If the plan is\
> active, it is deactivated first before resetting.\
> Returns NOT\_FOUND if no active plan exists.\
> Returns FAILED\_PRECONDITION if the thread is currently generating.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceResetPlanBody":{"type":"object","properties":{},"description":"Request to reset all steps in a thread's plan back to pending."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan/active:reset":{"post":{"summary":"Reset Plan","description":"Resets all step statuses on the active plan back to pending.\n\nClears all step statuses and failure reasons. If the plan is\nactive, it is deactivated first before resetting.\nReturns NOT_FOUND if no active plan exists.\nReturns FAILED_PRECONDITION if the thread is currently generating.","operationId":"ResetPlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to reset.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceResetPlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Activate Plan

> Activates the plan for a thread. Snapshots the current template\
> plan and carries over statuses from any previous snapshot by id.\
> \
> Returns NOT\_FOUND if no plan template exists.\
> Returns FAILED\_PRECONDITION if the thread is currently generating,\
> the plan is already active, or the template has no phases.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceActivatePlanBody":{"type":"object","properties":{},"description":"Request to activate a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/plan:activate":{"post":{"summary":"Activate Plan","description":"Activates the plan for a thread. Snapshots the current template\nplan and carries over statuses from any previous snapshot by id.\n\nReturns NOT_FOUND if no plan template exists.\nReturns FAILED_PRECONDITION if the thread is currently generating,\nthe plan is already active, or the template has no phases.","operationId":"ActivatePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to activate.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceActivatePlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.","operationId":"StreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","description":"The ID of the agent that owns the thread.","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## Send Tool Call

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.","operationId":"SendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.","operationId":"SendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```","operationId":"UploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","description":"The ID of the agent that owns the thread.","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Compact Thread

> Starts context compaction for a thread.\
> \
> Compaction summarizes conversation history to reduce context size while\
> preserving essential information. This RPC emits a CompactStart event\
> and returns the compact\_id for tracking.\
> \
> The actual compaction is performed asynchronously. Once complete, a\
> CompactComplete event with the summary content should be added to the\
> thread using the returned compact\_id.\
> \
> While compaction is in progress (CompactStart without CompactComplete),\
> the UI should block user input.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StartCompactionResponse":{"type":"object","properties":{"compact_id":{"type":"string","description":"The unique ID assigned to this compaction operation."}},"description":"Response for starting context compaction."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStartCompactionBody":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"Optional. The event ID from which to start compaction.\nEvents from this ID onwards (inclusive) will be compacted.\nIf not specified, the entire conversation is compacted."}},"description":"Request to start context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. A CompactStart event is emitted immediately,\nand an external compaction process should later emit CompactComplete with the\nsummary."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:compact":{"post":{"summary":"Compact Thread","description":"Starts context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. This RPC emits a CompactStart event\nand returns the compact_id for tracking.\n\nThe actual compaction is performed asynchronously. Once complete, a\nCompactComplete event with the summary content should be added to the\nthread using the returned compact_id.\n\nWhile compaction is in progress (CompactStart without CompactComplete),\nthe UI should block user input.","operationId":"CompactThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StartCompactionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to compact.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStartCompactionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Fork Thread

> Forks (duplicates) a thread with all its data.\
> \
> Creates a new thread that is a complete copy of the source thread,\
> including events, feedback, memory customizations, scratchpad, plan,\
> and template config customizations.\
> Returns FAILED\_PRECONDITION if the source thread is currently generating.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceForkThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the new thread. Defaults to \"Fork of {source_title}\"."}},"description":"Request message for ForkThread (duplicate a thread with all its data)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:fork":{"post":{"summary":"Fork Thread","description":"Forks (duplicates) a thread with all its data.\n\nCreates a new thread that is a complete copy of the source thread,\nincluding events, feedback, memory customizations, scratchpad, plan,\nand template config customizations.\nReturns FAILED_PRECONDITION if the source thread is currently generating.","operationId":"ForkThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The source thread to fork.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceForkThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stop Thread

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.","operationId":"StopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.","operationId":"WakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The ID of the agent that owns the thread.","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Agent Versions

> Lists all versions of an agent.\
> \
> Returns version metadata in ascending order.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListAgentVersionsResponse":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1AgentVersionInfo"},"description":"All versions in ascending order."}},"description":"Response containing the version history of an agent."},"agentsV1AgentVersionInfo":{"type":"object","properties":{"version":{"type":"string","format":"uint64","description":"Auto-incrementing version number (1-based)."},"tags":{"type":"array","items":{"type":"string"},"description":"User-applied tags on this version."},"created_at":{"type":"string","format":"date-time","description":"When this version was created."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"}},"description":"Metadata for a single stored version of an agent."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions":{"get":{"summary":"List Agent Versions","description":"Lists all versions of an agent.\n\nReturns version metadata in ascending order.","operationId":"ListAgentVersions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListAgentVersionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"The agent ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Agent Version

> Fetches a specific version of an agent's full configuration by version number.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetAgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"The agent's unique identifier."},"name":{"type":"string","description":"The agent's display name."},"variables":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1VariableDefinition"},"description":"Variable definitions for thread-scoped configuration.\nVariables can be referenced in any config using `$varName` syntax."},"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"Sub-agents configured for this agent."},"description":{"type":"string","description":"Optional description of the agent's purpose."},"version":{"type":"string","format":"uint64","description":"The version number of the returned agent. When loaded by tag or version,\nthis is the resolved version. When loaded as latest, this is the latest version."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags applied to the returned version."},"auto_title_enabled":{"type":"boolean","description":"Whether the agent automatically generates a title and description for\neach new thread on the first user message."},"customization_explainer_enabled":{"type":"boolean","description":"Whether the agent generates a plain-English summary every time a\nthread's customization changes. The summaries are surfaced in the\ncustomization badge tooltip."},"abilities":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Ability"},"description":"The agent's abilities, as shown on the agent card."},"icon":{"type":"string","description":"The agent's effective icon, as a kebab-case Lucide icon name. Empty\nwhen the agent has no icon."}},"description":"Response message for GetAgent."},"agentsV1VariableDefinition":{"type":"object","properties":{"name":{"type":"string","description":"The variable name (used as `$name` in configs)."},"required":{"type":"boolean","description":"Whether this variable is required when creating a thread."},"default":{"type":"string","description":"Default value if not provided (only valid for non-required variables)."},"description":{"type":"string","description":"Human-readable description of what this variable is for."},"segment":{"type":"string","description":"URL path segment name for multi-tenant parent path routing.\nWhen set, this variable can be extracted from a parent path like\n`/organizations/acme/workspaces/dev` where `organizations` and `workspaces`\nare segment names. If not set, the variable `name` is used as the segment."},"fixed_value":{"type":"string","description":"Fixed value for this variable.\nWhen set, the variable is locked to this value and cannot be overridden.\nUnlike `default` (which can be overridden), a fixed value is immutable."}},"description":"Defines a variable that can be used in agent configuration.\n\nVariables are defined at the agent level and filled when creating a thread.\nThey can be referenced in any configuration value using `$varName` syntax."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"agentsV1Ability":{"type":"object","properties":{"name":{"type":"string","description":"Short label, e.g. \"web search\", \"PDF editing\", \"team memory\"."},"icon":{"type":"string","description":"Icon identifier, as a kebab-case Lucide icon name (e.g. \"file-text\",\n\"git-branch\", \"map-pin\")."},"description":{"type":"string","description":"Optional one-line description for a tooltip."}},"description":"A single human-readable agent capability shown on the agent card."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}":{"get":{"summary":"Get Agent Version","description":"Fetches a specific version of an agent's full configuration by version number.","operationId":"GetAgentVersion","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","description":"Required. The numeric version to fetch.","in":"path","required":true,"schema":{"type":"string","format":"uint64"}}],"tags":["Agents"]}}}}
```

## Restore Agent Version

> Restores a previous version as a new version at the head.\
> \
> The old version's template becomes the new latest version.\
> All existing versions are preserved.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1RestoreAgentVersionResponse":{"type":"object","properties":{"version":{"$ref":"#/components/schemas/agentsV1AgentVersionInfo"}},"description":"Response after restoring a previous agent version."},"agentsV1AgentVersionInfo":{"type":"object","properties":{"version":{"type":"string","format":"uint64","description":"Auto-incrementing version number (1-based)."},"tags":{"type":"array","items":{"type":"string"},"description":"User-applied tags on this version."},"created_at":{"type":"string","format":"date-time","description":"When this version was created."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"}},"description":"Metadata for a single stored version of an agent."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsAgentServiceRestoreAgentVersionBody":{"type":"object","properties":{},"description":"Request to restore a previous agent version as a new version at the head."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}:restore":{"post":{"summary":"Restore Agent Version","description":"Restores a previous version as a new version at the head.\n\nThe old version's template becomes the new latest version.\nAll existing versions are preserved.","operationId":"RestoreAgentVersion","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1RestoreAgentVersionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","description":"The version number to restore.","in":"path","required":true,"schema":{"type":"string","format":"uint64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsAgentServiceRestoreAgentVersionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Tag Agent Version

> Applies a tag to a specific agent version.\
> \
> Tags are immutable — a tag name can only be used once per agent.\
> To reassign a tag, untag it first, then re-tag.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsAgentServiceTagAgentVersionBody":{"type":"object","properties":{"tag":{"type":"string","description":"The tag name to apply."}},"description":"Request to apply a tag to a specific agent version."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}:tag":{"post":{"summary":"Tag Agent Version","description":"Applies a tag to a specific agent version.\n\nTags are immutable — a tag name can only be used once per agent.\nTo reassign a tag, untag it first, then re-tag.","operationId":"TagAgentVersion","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"The agent ID.","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","description":"The version number to tag.","in":"path","required":true,"schema":{"type":"string","format":"uint64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsAgentServiceTagAgentVersionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Duplicate Agent

> Duplicates an agent with all its configuration.\
> \
> Creates a new agent that is a complete copy of the source agent,\
> including generator, memory blocks, tool sources with adapters,\
> artifact stores, artifact types, event compactor, and variables.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DuplicateAgentResponse":{"type":"object","properties":{"id":{"type":"string","description":"The newly created agent's unique identifier."},"name":{"type":"string","description":"The agent's display name."}},"description":"Response message for DuplicateAgent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsAgentServiceDuplicateAgentBody":{"type":"object","properties":{"name":{"type":"string","description":"Optional name for the copy. Fails with ALREADY_EXISTS when the name's\nderived ID is taken. When omitted, defaults to \"Copy of {source_name}\",\nnumbered \"Copy of {source_name} (2)\", \"(3)\", ... until the ID is free."}},"description":"Request message for DuplicateAgent."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}:duplicate":{"post":{"summary":"Duplicate Agent","description":"Duplicates an agent with all its configuration.\n\nCreates a new agent that is a complete copy of the source agent,\nincluding generator, memory blocks, tool sources with adapters,\nartifact stores, artifact types, event compactor, and variables.","operationId":"DuplicateAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DuplicateAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent to duplicate.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsAgentServiceDuplicateAgentBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Export Agent

> Exports an agent configuration in the specified format.\
> \
> Returns the exported data as bytes with a suggested filename.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ExportAgentResponse":{"type":"object","properties":{"data":{"type":"string","format":"byte","description":"The exported agent data."},"filename":{"type":"string","description":"Suggested filename for the export (e.g., \"my-agent.yaml\")."},"content_type":{"type":"string","description":"MIME type of the exported data (e.g., \"application/x-yaml\")."}},"description":"Response message for ExportAgent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsAgentServiceExportAgentBody":{"type":"object","properties":{"format":{"type":"string","description":"Required. The export format kind (e.g., \"yaml\", \"kubernetes\")."},"config":{"type":"object","description":"Format-specific configuration options."}},"description":"Request message for ExportAgent.","required":["format"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents/{agent_id}:export":{"post":{"summary":"Export Agent","description":"Exports an agent configuration in the specified format.\n\nReturns the exported data as bytes with a suggested filename.","operationId":"ExportAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ExportAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","description":"Required. The agent to export.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsAgentServiceExportAgentBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Import Agent

> Imports an agent configuration from the specified format.\
> \
> Parses and validates the data, saves the agent to the store.\
> Sub-agent dependencies must exist or be included in the import bundle.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ImportAgentResponse":{"type":"object","properties":{"agent_id":{"type":"string","description":"The imported agent's unique identifier."},"agent_name":{"type":"string","description":"The imported agent's display name."},"saved_sub_agent_ids":{"type":"array","items":{"type":"string"},"description":"IDs of sub-agents that were saved to the store as part of the import."},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-fatal warnings encountered during import."},"version":{"type":"string","format":"uint64","description":"Resulting latest version of the imported root agent. When the agent\nalready existed and the spec changed, this is the newly created\nversion; when the spec was identical, it is the unchanged latest\nversion (and a warning is included)."}},"description":"Response message for ImportAgent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsV1ImportAgentRequest":{"type":"object","properties":{"format":{"type":"string","description":"Required. The import format kind (e.g., \"yaml\", \"kubernetes\")."},"data":{"type":"string","format":"byte","description":"Required. Raw file content to import."},"config":{"type":"object","description":"Format-specific configuration options."}},"description":"Request message for ImportAgent.","required":["format","data"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/agents:import":{"post":{"summary":"Import Agent","description":"Imports an agent configuration from the specified format.\n\nParses and validates the data, saves the agent to the store.\nSub-agent dependencies must exist or be included in the import bundle.","operationId":"ImportAgent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ImportAgentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ImportAgentRequest"}}},"description":"Request message for ImportAgent.","required":true},"tags":["Agents"]}}}}
```

## List Threads (Hermes, automation)

> Lists all threads for an agent.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads":{"get":{"summary":"List Threads (Hermes, automation)","description":"Lists all threads for an agent.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"AutomationHermesListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Hermes, automation)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads":{"post":{"summary":"Create Thread (Hermes, automation)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread (Hermes, automation)

> Gets a thread by ID.\
> \
> Returns thread metadata and event count without loading the full event history.\
> Returns NOT\_FOUND if the thread doesn't exist.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`GetThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}":{"get":{"summary":"Get Thread (Hermes, automation)","description":"Gets a thread by ID.\n\nReturns thread metadata and event count without loading the full event history.\nReturns NOT_FOUND if the thread doesn't exist.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `GetThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesGetThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Thread (Hermes, automation)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Hermes, automation)","description":"Deletes a thread and all its events.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesDeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Thread (Hermes, automation)

> Updates a thread's title and/or description.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`UpdateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional new title for the thread."},"description":{"type":"string","description":"Optional new description for the thread."}},"description":"Request to update a thread's metadata."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}":{"patch":{"summary":"Update Thread (Hermes, automation)","description":"Updates a thread's title and/or description.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `UpdateThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesUpdateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread Context (Hermes, automation)

> Gets thread context information including all context items with token counts.\
> \
> Returns a unified view of all items contributing to the context window:\
> \- Memory blocks (fixed and volatile)\
> \- Enabled tools (fixed)\
> \- Conversation history (compactable)\
> \
> Each item includes its token count for context budget management.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`GetThreadContext\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetThreadContextResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ContextItem"},"description":"List of context items contributing to the thread's context window.","readOnly":true},"model_info":{"$ref":"#/components/schemas/agentsV1ModelInfo"},"summary":{"$ref":"#/components/schemas/agentsV1ContextSummary"},"auto_compact_tokens":{"type":"integer","format":"int64","description":"Prompt token count at which the next completed turn triggers\nauto-compaction.\n\nAbsent when no compactor is configured, in which case auto-compaction\nnever fires, or when the model does not report a context window.","readOnly":true}},"description":"Response containing thread context information."},"agentsV1ContextItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the context item.","readOnly":true},"label":{"type":"string","description":"Human-readable label for display.","readOnly":true},"token_count":{"type":"integer","format":"int64","description":"Number of tokens this item consumes.","readOnly":true},"category":{"$ref":"#/components/schemas/agentsV1ContextCategory"},"memory_block":{"$ref":"#/components/schemas/agentsV1MemoryBlockRef"},"tool":{"$ref":"#/components/schemas/agentsV1ToolRef"}},"description":"A single item contributing to the thread's context window."},"agentsV1ContextCategory":{"type":"string","enum":["CONTEXT_CATEGORY_UNSPECIFIED","CONTEXT_CATEGORY_FIXED","CONTEXT_CATEGORY_VOLATILE","CONTEXT_CATEGORY_COMPACTABLE"],"default":"CONTEXT_CATEGORY_UNSPECIFIED","description":"Category of context items for token budget management.\n\n - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category.\n - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools).\n - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks).\n - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history)."},"agentsV1MemoryBlockRef":{"type":"object","properties":{"block_id":{"type":"string","description":"The unique block identifier (deterministic hash of block name).","readOnly":true},"type":{"type":"string","description":"The block type (e.g., \"text\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the block type.","readOnly":true},"description":{"type":"string","description":"Description of the memory block.","readOnly":true},"scope":{"$ref":"#/components/schemas/agentsV1ScopeLevel"},"mutable":{"type":"boolean","description":"Whether the block is mutable.","readOnly":true}},"description":"Lightweight memory block reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits content and config to keep responses lightweight."},"agentsV1ScopeLevel":{"type":"string","enum":["SCOPE_LEVEL_UNSPECIFIED","SCOPE_LEVEL_AGENT","SCOPE_LEVEL_THREAD","SCOPE_LEVEL_USER"],"default":"SCOPE_LEVEL_UNSPECIFIED","description":"The scope level for a memory block's content storage.\n\n - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT).\n - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads.\n - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content.\n - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content,\nwhich follows them across all of their threads with the agent and is\ninvisible to other users. Only kinds whose allowed_scopes include it\n(or list no restriction) accept it."},"agentsV1ToolRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool identifier (hash of the original tool name).","readOnly":true},"name":{"type":"string","description":"The tool name (may be adapted name if adapters are applied).","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted.","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations).","readOnly":true}},"description":"Lightweight tool reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits parameters_schema to keep responses lightweight."},"agentsV1ModelInfo":{"type":"object","properties":{"model_id":{"type":"string","description":"Model identifier (e.g., \"gpt-4o\", \"claude-3-opus\").","readOnly":true},"max_context_tokens":{"type":"integer","format":"int64","description":"Maximum context length in tokens.","readOnly":true},"max_output_tokens":{"type":"integer","format":"int64","description":"Maximum output tokens.","readOnly":true},"supports_vision":{"type":"boolean","description":"Whether the model supports vision/images.","readOnly":true},"supports_tools":{"type":"boolean","description":"Whether the model supports tool/function calling.","readOnly":true},"supports_structured_output":{"type":"boolean","description":"Whether the model supports structured output (JSON mode).","readOnly":true},"supports_streaming":{"type":"boolean","description":"Whether the model supports streaming responses.","readOnly":true},"supports_reasoning":{"type":"boolean","description":"Whether the model supports reasoning (chain-of-thought).","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"GPT-4o\", \"Claude Sonnet 4.5\").","readOnly":true},"family":{"type":"string","description":"Model family grouping (e.g., \"gpt-4o\", \"claude-4.5\", \"qwen2\").","readOnly":true},"license":{"type":"string","description":"License information (e.g., for open-weight models).","readOnly":true},"parameter_count":{"type":"string","format":"uint64","description":"Number of model parameters.","readOnly":true},"quantization":{"type":"string","description":"Quantization level (e.g., \"Q4_K_M\", \"Q8_0\").","readOnly":true},"supports_documents":{"type":"boolean","description":"Whether the model supports document inputs (PDFs, text files).","readOnly":true},"max_inline_artifact_bytes":{"type":"string","format":"uint64","description":"Maximum size of a single tool result that can be inlined into a\ngeneration request, in raw bytes. Already accounts for base64 expansion\nand a safety margin for request overhead.","readOnly":true},"deprecated":{"type":"boolean","description":"Whether the model is deprecated: still usable, but slated for retirement.","readOnly":true},"retired":{"type":"boolean","description":"Whether the model is retired: loadable (so existing threads/agents don't\nbreak) but generation is refused.","readOnly":true},"replacement_model":{"type":"string","description":"Recommended replacement model id when deprecated or retired.","readOnly":true},"pricing":{"$ref":"#/components/schemas/agentsV1ModelPricing"}},"description":"Information about a model and its capabilities."},"agentsV1ModelPricing":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DatedRates"},"description":"Effective-dated rate rows. Windows should not overlap; if they do, the\nearliest-starting matching row wins so the outcome is deterministic.","readOnly":true}},"description":"Complete pricing knowledge for one model: its effective-dated rate rows.\n\nAn empty `rows` list is a valid \"priced at zero\" card for local models —\ndistinct from a model carrying no `ModelPricing` at all, which means its\ncost is unknown, not free."},"agentsV1DatedRates":{"type":"object","properties":{"effective_from":{"type":"string","format":"date-time","description":"Inclusive start of this row's validity. Absent = open-ended past.","readOnly":true},"effective_until":{"type":"string","format":"date-time","description":"Exclusive end of this row's validity. Absent = open-ended future.","readOnly":true},"base":{"$ref":"#/components/schemas/agentsV1RateCard"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1TierRates"},"description":"Long-context tiers: token-threshold bands above `base`, ascending by\n`threshold_tokens`. Empty = flat pricing. A request's total prompt size\nselects the highest tier whose threshold it reaches, or `base` below\nevery threshold.","readOnly":true}},"description":"One effective-dated pricing row: the rates in force during a validity\nwindow. A model whose price changes on a schedule carries several rows\ndiffering only in rates and effective bounds."},"agentsV1RateCard":{"type":"object","properties":{"input_per_mtok":{"type":"number","format":"double","description":"Fresh (uncached) input, USD per million tokens.","readOnly":true},"output_per_mtok":{"type":"number","format":"double","description":"Output, USD per million tokens. Includes reasoning/thinking tokens.","readOnly":true},"cache_read_per_mtok":{"type":"number","format":"double","description":"Tokens served from cache, USD per million tokens.","readOnly":true},"cache_write_per_mtok":{"type":"number","format":"double","description":"Cache writes at any TTL, USD per million tokens — for providers with a\nsingle write rate regardless of TTL.","readOnly":true},"cache_write_by_ttl":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWriteRate"},"description":"Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`.","readOnly":true}},"description":"One complete set of USD-per-million-token rates. A missing cache rate is\nnot zero — it means the dimension is unpublished, and cost computation\nfalls back loudly (billed at the fresh-input rate, flagged estimated)."},"agentsV1CacheWriteRate":{"type":"object","properties":{"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket,\n3600 for a 1-hour bucket).","readOnly":true},"per_mtok":{"type":"number","format":"double","description":"USD per million tokens written into this bucket.","readOnly":true}},"description":"USD rate for cache writes at one specific TTL bucket."},"agentsV1TierRates":{"type":"object","properties":{"threshold_tokens":{"type":"integer","format":"int64","description":"Prompt-size threshold (total prompt tokens: fresh + cache read + cache\nwrite) at which these rates activate.","readOnly":true},"card":{"$ref":"#/components/schemas/agentsV1RateCard"}},"description":"One long-context tier band: requests whose total prompt tokens meet or\nexceed `threshold_tokens` (and fall below the next tier's threshold, when\none exists) bill the entire request — every class, input and output — at\n`card` instead of the base card."},"agentsV1ContextSummary":{"type":"object","properties":{"fixed_tokens":{"type":"integer","format":"int64","description":"Tokens used by fixed context (immutable memory + tools).","readOnly":true},"volatile_tokens":{"type":"integer","format":"int64","description":"Tokens used by volatile context (mutable memory).","readOnly":true},"compactable_tokens":{"type":"integer","format":"int64","description":"Tokens used by compactable context (conversation).","readOnly":true},"total_used_tokens":{"type":"integer","format":"int64","description":"Total tokens currently in use.","readOnly":true},"available_tokens":{"type":"integer","format":"int64","description":"Tokens available before hitting the context limit.","readOnly":true}},"description":"Summary of token usage by category."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/context":{"get":{"summary":"Get Thread Context (Hermes, automation)","description":"Gets thread context information including all context items with token counts.\n\nReturns a unified view of all items contributing to the context window:\n- Memory blocks (fixed and volatile)\n- Enabled tools (fixed)\n- Conversation history (compactable)\n\nEach item includes its token count for context budget management.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`.","operationId":"AutomationHermesGetThreadContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetThreadContextResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"The thread ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events (Hermes, automation)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Hermes, automation)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"AutomationHermesGetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message And Wait (Hermes, automation)

> Sends a message and streams back response events synchronously.\
> \
> This RPC adds user input to the specified thread and returns a stream\
> of events representing the assistant's response. Events include output text,\
> tool calls, and completion metadata.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`SendMessageAndWait\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageSyncBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message and stream response events synchronously."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/events":{"post":{"summary":"Send Message And Wait (Hermes, automation)","description":"Sends a message and streams back response events synchronously.\n\nThis RPC adds user input to the specified thread and returns a stream\nof events representing the assistant's response. Events include output text,\ntool calls, and completion metadata.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`.","operationId":"AutomationHermesSendMessageAndWait","responses":{"200":{"description":"A successful response.(streaming responses)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/agentsV1Event"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"Stream result of v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageSyncBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Set Thread Feedback (Hermes, automation)

> Sets feedback (like/dislike) for a generation response.\
> \
> Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\
> Setting the same feedback that already exists is a no-op.\
> Use FEEDBACK\_TYPE\_UNSPECIFIED to clear existing feedback.\
> \
> Feedback is stored with the thread and is purely for analytics/UI purposes.\
> It is not visible to the LLM.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`SetThreadFeedback\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SetFeedbackResponse":{"type":"object","properties":{"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"previous_feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Response for setting feedback on a generation."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSetFeedbackBody":{"type":"object","properties":{"generation_id":{"type":"string","description":"Required. The generation ID (from GenerationComplete.id)."},"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Request to set feedback for a generation response."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/feedback":{"post":{"summary":"Set Thread Feedback (Hermes, automation)","description":"Sets feedback (like/dislike) for a generation response.\n\nFeedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\nSetting the same feedback that already exists is a no-op.\nUse FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback.\n\nFeedback is stored with the thread and is purely for analytics/UI purposes.\nIt is not visible to the LLM.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`.","operationId":"AutomationHermesSetThreadFeedback","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SetFeedbackResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread containing the generation.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSetFeedbackBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Message (Hermes, automation)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/input":{"post":{"summary":"Send Message (Hermes, automation)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"AutomationHermesSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Hermes, automation)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Hermes, automation)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"AutomationHermesStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## List Sub Agents (Hermes, automation)

> Lists sub-agents configured for a thread.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`ListSubAgents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListSubAgentsResponse":{"type":"object","properties":{"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"The sub-agents configured for the thread."},"is_customized":{"type":"boolean","description":"Whether this represents a per-thread customization (vs inherited from agent)."}},"description":"Response message for ListSubAgents."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/sub-agents":{"get":{"summary":"List Sub Agents (Hermes, automation)","description":"Lists sub-agents configured for a thread.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`.","operationId":"AutomationHermesListSubAgents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListSubAgentsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread whose sub-agents to list.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Tool Call (Hermes, automation)

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`SendToolCall\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call (Hermes, automation)","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `SendToolCall` on `/agents/{agent_id}`.","operationId":"AutomationHermesSendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result (Hermes, automation)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Hermes, automation)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"AutomationHermesSendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File (Hermes, automation)

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`UploadThreadFile\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File (Hermes, automation)","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`.","operationId":"AutomationHermesUploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Compact Thread (Hermes, automation)

> Starts context compaction for a thread.\
> \
> Compaction summarizes conversation history to reduce context size while\
> preserving essential information. This RPC emits a CompactStart event\
> and returns the compact\_id for tracking.\
> \
> The actual compaction is performed asynchronously. Once complete, a\
> CompactComplete event with the summary content should be added to the\
> thread using the returned compact\_id.\
> \
> While compaction is in progress (CompactStart without CompactComplete),\
> the UI should block user input.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`CompactThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StartCompactionResponse":{"type":"object","properties":{"compact_id":{"type":"string","description":"The unique ID assigned to this compaction operation."}},"description":"Response for starting context compaction."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStartCompactionBody":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"Optional. The event ID from which to start compaction.\nEvents from this ID onwards (inclusive) will be compacted.\nIf not specified, the entire conversation is compacted."}},"description":"Request to start context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. A CompactStart event is emitted immediately,\nand an external compaction process should later emit CompactComplete with the\nsummary."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:compact":{"post":{"summary":"Compact Thread (Hermes, automation)","description":"Starts context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. This RPC emits a CompactStart event\nand returns the compact_id for tracking.\n\nThe actual compaction is performed asynchronously. Once complete, a\nCompactComplete event with the summary content should be added to the\nthread using the returned compact_id.\n\nWhile compaction is in progress (CompactStart without CompactComplete),\nthe UI should block user input.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `CompactThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesCompactThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StartCompactionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to compact.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStartCompactionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Fork Thread (Hermes, automation)

> Forks (duplicates) a thread with all its data.\
> \
> Creates a new thread that is a complete copy of the source thread,\
> including events, feedback, memory customizations, scratchpad, plan,\
> and template config customizations.\
> Returns FAILED\_PRECONDITION if the source thread is currently generating.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`ForkThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceForkThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the new thread. Defaults to \"Fork of {source_title}\"."}},"description":"Request message for ForkThread (duplicate a thread with all its data)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:fork":{"post":{"summary":"Fork Thread (Hermes, automation)","description":"Forks (duplicates) a thread with all its data.\n\nCreates a new thread that is a complete copy of the source thread,\nincluding events, feedback, memory customizations, scratchpad, plan,\nand template config customizations.\nReturns FAILED_PRECONDITION if the source thread is currently generating.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `ForkThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesForkThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The source thread to fork.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceForkThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stop Thread (Hermes, automation)

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`StopThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread (Hermes, automation)","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `StopThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesStopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread (Hermes, automation)

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.\
> \
> Targets the built-in \`hermes\` agent in the automation scope; the generic form is \`WakeThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/hermes/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread (Hermes, automation)","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.\n\nTargets the built-in `hermes` agent in the automation scope; the generic form is `WakeThread` on `/agents/{agent_id}`.","operationId":"AutomationHermesWakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Threads (Prime, automation)

> Lists all threads for an agent.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads":{"get":{"summary":"List Threads (Prime, automation)","description":"Lists all threads for an agent.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"AutomationPrimeListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Prime, automation)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads":{"post":{"summary":"Create Thread (Prime, automation)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"AutomationPrimeCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread Events (Prime, automation)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Prime, automation)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"AutomationPrimeGetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message (Prime, automation)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/input":{"post":{"summary":"Send Message (Prime, automation)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"AutomationPrimeSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Prime, automation)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Prime, automation)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"AutomationPrimeStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## Send Tool Call (Prime, automation)

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`SendToolCall\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call (Prime, automation)","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `SendToolCall` on `/agents/{agent_id}`.","operationId":"AutomationPrimeSendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result (Prime, automation)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Prime, automation)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"AutomationPrimeSendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File (Prime, automation)

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`UploadThreadFile\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File (Prime, automation)","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`.","operationId":"AutomationPrimeUploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Stop Thread (Prime, automation)

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`StopThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread (Prime, automation)","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `StopThread` on `/agents/{agent_id}`.","operationId":"AutomationPrimeStopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread (Prime, automation)

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.\
> \
> Targets the built-in \`prime\` agent in the automation scope; the generic form is \`WakeThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/prime/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread (Prime, automation)","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.\n\nTargets the built-in `prime` agent in the automation scope; the generic form is `WakeThread` on `/agents/{agent_id}`.","operationId":"AutomationPrimeWakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Threads (Quill2, automation)

> Lists all threads for an agent.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads":{"get":{"summary":"List Threads (Quill2, automation)","description":"Lists all threads for an agent.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"AutomationQuill2ListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Quill2, automation)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads":{"post":{"summary":"Create Thread (Quill2, automation)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2CreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread (Quill2, automation)

> Gets a thread by ID.\
> \
> Returns thread metadata and event count without loading the full event history.\
> Returns NOT\_FOUND if the thread doesn't exist.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}":{"get":{"summary":"Get Thread (Quill2, automation)","description":"Gets a thread by ID.\n\nReturns thread metadata and event count without loading the full event history.\nReturns NOT_FOUND if the thread doesn't exist.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Thread (Quill2, automation)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Quill2, automation)","description":"Deletes a thread and all its events.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2DeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Thread (Quill2, automation)

> Updates a thread's title and/or description.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`UpdateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional new title for the thread."},"description":{"type":"string","description":"Optional new description for the thread."}},"description":"Request to update a thread's metadata."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}":{"patch":{"summary":"Update Thread (Quill2, automation)","description":"Updates a thread's title and/or description.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `UpdateThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2UpdateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Artifacts (Quill2, automation)

> Lists artifacts with optional filters.\
> Supports S3-style delimiter for folder navigation.\
> Thread ID is required for variable-scoped artifact access.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`ListArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListArtifactsResponse":{"type":"object","properties":{"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Artifact"},"description":"Artifacts matching the filter."},"common_prefixes":{"type":"array","items":{"type":"string"},"description":"Common prefixes (\"folders\") when delimiter is set."}},"description":"Response for ListArtifacts."},"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts":{"get":{"summary":"List Artifacts (Quill2, automation)","description":"Lists artifacts with optional filters.\nSupports S3-style delimiter for folder navigation.\nThread ID is required for variable-scoped artifact access.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `ListArtifacts` on `/agents/{agent_id}`.","operationId":"AutomationQuill2ListArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"prefix","description":"Optional. Filter by URI prefix (e.g., \"workspace://src/\").\nIf not specified, lists from all stores.","in":"query","required":false,"schema":{"type":"string"}},{"name":"delimiter","description":"Optional. Delimiter for S3-style folder grouping (typically \"/\").","in":"query","required":false,"schema":{"type":"string"}},{"name":"mime_type","description":"Optional. Filter by MIME type prefix (e.g., \"text/\", \"image/\").","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","description":"Optional. Maximum number of results.","in":"query","required":false,"schema":{"type":"integer","format":"int64"}}],"tags":["Agents"]}}}}
```

## Get Artifact (Quill2, automation)

> Gets artifact metadata by URI.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetArtifact\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}":{"get":{"summary":"Get Artifact (Quill2, automation)","description":"Gets artifact metadata by URI.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifact` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetArtifact","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Artifact"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Artifact (Quill2, automation)

> Creates or updates an artifact.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`UpdateArtifact\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateArtifactBody":{"type":"object","properties":{"mime_type":{"type":"string","description":"Required. The MIME type."},"data":{"type":"string","format":"byte","description":"Required. The artifact content."},"description":{"type":"string","description":"Optional description."}},"description":"Request for UpdateArtifact.","required":["mime_type","data"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}":{"put":{"summary":"Update Artifact (Quill2, automation)","description":"Creates or updates an artifact.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `UpdateArtifact` on `/agents/{agent_id}`.","operationId":"AutomationQuill2UpdateArtifact","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Artifact"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateArtifactBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete Artifact (Quill2, automation)

> Deletes an artifact by URI.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`DeleteArtifact\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}":{"delete":{"summary":"Delete Artifact (Quill2, automation)","description":"Deletes an artifact by URI.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `DeleteArtifact` on `/agents/{agent_id}`.","operationId":"AutomationQuill2DeleteArtifact","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Artifact Content (Quill2, automation)

> Gets artifact content by URI.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetArtifactContent\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ArtifactContentResponse":{"type":"object","properties":{"artifact":{"$ref":"#/components/schemas/agentsV1Artifact"},"data":{"type":"string","format":"byte","description":"The raw content bytes."}},"description":"Response for GetArtifactContent."},"agentsV1Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (URI format: {store_id}://{path}).","readOnly":true},"name":{"type":"string","description":"Path-based name (e.g., \"src/main.rs\", \"docs/design.md\").","readOnly":true},"mime_type":{"type":"string","description":"MIME type (e.g., \"text/plain\", \"application/json\", \"image/png\").","readOnly":true},"size":{"type":"string","format":"uint64","description":"Size in bytes.","readOnly":true},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","readOnly":true},"updated_at":{"type":"string","format":"date-time","description":"Last modification timestamp.","readOnly":true},"description":{"type":"string","description":"Optional description."},"version":{"type":"string","format":"uint64","description":"Optimistic concurrency version (epoch nanoseconds).","readOnly":true}},"description":"An artifact stored in an artifact store."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}:content":{"get":{"summary":"Get Artifact Content (Quill2, automation)","description":"Gets artifact content by URI.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifactContent` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetArtifactContent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ArtifactContentResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Artifact Diff (Quill2, automation)

> Gets the diff for a single staged artifact.\
> \
> Returns the unified diff for a specific artifact if it has staged changes.\
> Returns empty diff for binary files or if no changes exist.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetArtifactDiff\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetArtifactDiffResponse":{"type":"object","properties":{"has_changes":{"type":"boolean","description":"Whether this artifact has staged changes."},"change":{"$ref":"#/components/schemas/agentsV1StagedChange"},"diff":{"type":"string","description":"Unified diff content.\nEmpty for binary files, deleted artifacts, or if no changes."}},"description":"Response for GetArtifactDiff."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts/{artifact_uri}:diff":{"get":{"summary":"Get Artifact Diff (Quill2, automation)","description":"Gets the diff for a single staged artifact.\n\nReturns the unified diff for a specific artifact if it has staged changes.\nReturns empty diff for binary files or if no changes exist.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifactDiff` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetArtifactDiff","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetArtifactDiffResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"artifact_uri","description":"Required. The artifact URI (e.g., \"workspace://src/main.rs\"). Percent-encode the URI in the path, for example `workspace%3A%2F%2Fsrc%2Fmain.rs`.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Commit Artifacts (Quill2, automation)

> Commits staged artifact changes to the underlying store.\
> \
> Persists all staged changes (additions, modifications, deletions) to\
> the underlying store. For stores without staging, this is a no-op.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`CommitArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1CommitArtifactsResponse":{"type":"object","properties":{"committed_count":{"type":"integer","format":"int64","description":"Number of artifacts committed."},"additions":{"type":"integer","format":"int64","description":"Number of additions committed."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications committed."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions committed."},"version":{"type":"string","description":"New artifact version produced by this commit, if the store versions its\ncontents. Absent for stores without a version concept."}},"description":"Response for CommitArtifacts."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCommitArtifactsBody":{"type":"object","properties":{"prefix":{"type":"string","description":"Optional. Store prefix to limit commit scope (e.g., \"workspace://\").\nIf not specified, commits all staged changes across all stores."}},"description":"Request for CommitArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:commit":{"post":{"summary":"Commit Artifacts (Quill2, automation)","description":"Commits staged artifact changes to the underlying store.\n\nPersists all staged changes (additions, modifications, deletions) to\nthe underlying store. For stores without staging, this is a no-op.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `CommitArtifacts` on `/agents/{agent_id}`.","operationId":"AutomationQuill2CommitArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1CommitArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCommitArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Diff Artifacts (Quill2, automation)

> Gets staged artifact changes with optional diff content.\
> \
> Returns information about artifacts that have been modified but not yet\
> committed. For stores with staging enabled, this shows pending changes.\
> For stores without staging, returns an empty response.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`DiffArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DiffArtifactsResponse":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DiffEntry"},"description":"List of staged changes with optional diff content."},"total_changes":{"type":"integer","format":"int64","description":"Total number of staged changes."},"additions":{"type":"integer","format":"int64","description":"Number of additions."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions."}},"description":"Response for DiffArtifacts."},"agentsV1DiffEntry":{"type":"object","properties":{"change":{"$ref":"#/components/schemas/agentsV1StagedChange"},"diff":{"type":"string","description":"Unified diff content (only if include_content was true).\nEmpty for binary files or deleted artifacts."}},"description":"A diff entry with optional content."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDiffArtifactsBody":{"type":"object","properties":{"prefix":{"type":"string","description":"Optional. Store prefix to limit diff scope (e.g., \"workspace://\").\nIf not specified, returns diff for all stores."},"include_content":{"type":"boolean","description":"Optional. Include unified diff content for each change.\nDefault is false (summary only)."}},"description":"Request for DiffArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:diff":{"post":{"summary":"Diff Artifacts (Quill2, automation)","description":"Gets staged artifact changes with optional diff content.\n\nReturns information about artifacts that have been modified but not yet\ncommitted. For stores with staging enabled, this shows pending changes.\nFor stores without staging, returns an empty response.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `DiffArtifacts` on `/agents/{agent_id}`.","operationId":"AutomationQuill2DiffArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DiffArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDiffArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Discard Artifacts (Quill2, automation)

> Discards all staged artifact changes without committing.\
> \
> Clears all pending changes (additions, modifications, deletions) from\
> the staging area. For stores without staging, this is a no-op.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`DiscardArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1DiscardArtifactsResponse":{"type":"object","properties":{"discarded_count":{"type":"integer","format":"int64","description":"Number of artifacts discarded."},"additions":{"type":"integer","format":"int64","description":"Number of additions discarded."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications discarded."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions discarded."}},"description":"Response for DiscardArtifacts."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDiscardArtifactsBody":{"type":"object","properties":{},"description":"Request for DiscardArtifacts."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:discard":{"post":{"summary":"Discard Artifacts (Quill2, automation)","description":"Discards all staged artifact changes without committing.\n\nClears all pending changes (additions, modifications, deletions) from\nthe staging area. For stores without staging, this is a no-op.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `DiscardArtifacts` on `/agents/{agent_id}`.","operationId":"AutomationQuill2DiscardArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1DiscardArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDiscardArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Grep Artifacts (Quill2, automation)

> Searches artifact contents using regex pattern matching.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GrepArtifacts\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GrepArtifactsResponse":{"type":"object","properties":{"pattern":{"type":"string","description":"The pattern that was searched."},"match_count":{"type":"integer","format":"int64","description":"Total number of matches found (may exceed matches size if limited)."},"matches":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1GrepMatch"},"description":"The matches (may be limited by request limit)."}},"description":"Response for GrepArtifacts."},"agentsV1GrepMatch":{"type":"object","properties":{"id":{"type":"string","description":"Artifact ID containing the match.","readOnly":true},"name":{"type":"string","description":"Artifact name/path.","readOnly":true},"line":{"type":"integer","format":"int64","description":"Line number (1-indexed).","readOnly":true},"content":{"type":"string","description":"The matching line content.","readOnly":true},"context_before":{"type":"array","items":{"type":"string"},"description":"Lines before the match (context).","readOnly":true},"context_after":{"type":"array","items":{"type":"string"},"description":"Lines after the match (context).","readOnly":true}},"description":"A single grep match within an artifact."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceGrepArtifactsBody":{"type":"object","properties":{"pattern":{"type":"string","description":"Required. Regex pattern to search for."},"prefix":{"type":"string","description":"Optional. URI prefix to limit search scope (e.g., \"workspace://src/\")."},"glob":{"type":"string","description":"Optional. Glob pattern to filter files (e.g., \"*.rs\")."},"ignore_case":{"type":"boolean","description":"Optional. Case-insensitive search."},"context_lines":{"type":"integer","format":"int64","description":"Optional. Number of context lines before/after each match."},"limit":{"type":"integer","format":"int64","description":"Optional. Maximum number of matches to return."}},"description":"Request for GrepArtifacts.","required":["pattern"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:grep":{"post":{"summary":"Grep Artifacts (Quill2, automation)","description":"Searches artifact contents using regex pattern matching.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GrepArtifacts` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GrepArtifacts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GrepArtifactsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceGrepArtifactsBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Artifacts Staging Summary (Quill2, automation)

> Gets a summary of staged artifact changes.\
> \
> Returns a lightweight summary of pending changes including counts and\
> change metadata without diff content. Use DiffArtifacts for full diffs.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetArtifactsStagingSummary\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetArtifactsStagingSummaryResponse":{"type":"object","properties":{"staging_enabled":{"type":"boolean","description":"Whether staging is enabled for any stores."},"changes":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1StagedChange"},"description":"List of staged changes (metadata only, no diff content)."},"total_changes":{"type":"integer","format":"int64","description":"Total number of staged changes."},"additions":{"type":"integer","format":"int64","description":"Number of additions."},"modifications":{"type":"integer","format":"int64","description":"Number of modifications."},"deletions":{"type":"integer","format":"int64","description":"Number of deletions."}},"description":"Response for GetArtifactsStagingSummary."},"agentsV1StagedChange":{"type":"object","properties":{"id":{"type":"string","description":"The artifact URI (e.g., \"workspace://src/main.rs\")."},"change_type":{"$ref":"#/components/schemas/agentsV1ChangeType"},"size":{"type":"string","format":"uint64","description":"Size in bytes (for added/modified artifacts)."}},"description":"A staged change to an artifact."},"agentsV1ChangeType":{"type":"string","enum":["CHANGE_TYPE_UNSPECIFIED","CHANGE_TYPE_ADDED","CHANGE_TYPE_MODIFIED","CHANGE_TYPE_DELETED"],"default":"CHANGE_TYPE_UNSPECIFIED","description":"Type of change for a staged artifact.\n\n - CHANGE_TYPE_UNSPECIFIED: Unspecified change type.\n - CHANGE_TYPE_ADDED: Artifact was added.\n - CHANGE_TYPE_MODIFIED: Artifact was modified.\n - CHANGE_TYPE_DELETED: Artifact was deleted."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/artifacts:staging":{"get":{"summary":"Get Artifacts Staging Summary (Quill2, automation)","description":"Gets a summary of staged artifact changes.\n\nReturns a lightweight summary of pending changes including counts and\nchange metadata without diff content. Use DiffArtifacts for full diffs.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetArtifactsStagingSummary` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetArtifactsStagingSummary","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetArtifactsStagingSummaryResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. Thread ID for variable-scoped artifact access.","in":"path","required":true,"schema":{"type":"string"}},{"name":"prefix","description":"Optional. Store prefix to limit summary scope (e.g., \"workspace://\").\nIf not specified, returns summary for all stores.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Context (Quill2, automation)

> Gets thread context information including all context items with token counts.\
> \
> Returns a unified view of all items contributing to the context window:\
> \- Memory blocks (fixed and volatile)\
> \- Enabled tools (fixed)\
> \- Conversation history (compactable)\
> \
> Each item includes its token count for context budget management.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetThreadContext\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetThreadContextResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ContextItem"},"description":"List of context items contributing to the thread's context window.","readOnly":true},"model_info":{"$ref":"#/components/schemas/agentsV1ModelInfo"},"summary":{"$ref":"#/components/schemas/agentsV1ContextSummary"},"auto_compact_tokens":{"type":"integer","format":"int64","description":"Prompt token count at which the next completed turn triggers\nauto-compaction.\n\nAbsent when no compactor is configured, in which case auto-compaction\nnever fires, or when the model does not report a context window.","readOnly":true}},"description":"Response containing thread context information."},"agentsV1ContextItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the context item.","readOnly":true},"label":{"type":"string","description":"Human-readable label for display.","readOnly":true},"token_count":{"type":"integer","format":"int64","description":"Number of tokens this item consumes.","readOnly":true},"category":{"$ref":"#/components/schemas/agentsV1ContextCategory"},"memory_block":{"$ref":"#/components/schemas/agentsV1MemoryBlockRef"},"tool":{"$ref":"#/components/schemas/agentsV1ToolRef"}},"description":"A single item contributing to the thread's context window."},"agentsV1ContextCategory":{"type":"string","enum":["CONTEXT_CATEGORY_UNSPECIFIED","CONTEXT_CATEGORY_FIXED","CONTEXT_CATEGORY_VOLATILE","CONTEXT_CATEGORY_COMPACTABLE"],"default":"CONTEXT_CATEGORY_UNSPECIFIED","description":"Category of context items for token budget management.\n\n - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category.\n - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools).\n - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks).\n - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history)."},"agentsV1MemoryBlockRef":{"type":"object","properties":{"block_id":{"type":"string","description":"The unique block identifier (deterministic hash of block name).","readOnly":true},"type":{"type":"string","description":"The block type (e.g., \"text\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the block type.","readOnly":true},"description":{"type":"string","description":"Description of the memory block.","readOnly":true},"scope":{"$ref":"#/components/schemas/agentsV1ScopeLevel"},"mutable":{"type":"boolean","description":"Whether the block is mutable.","readOnly":true}},"description":"Lightweight memory block reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits content and config to keep responses lightweight."},"agentsV1ScopeLevel":{"type":"string","enum":["SCOPE_LEVEL_UNSPECIFIED","SCOPE_LEVEL_AGENT","SCOPE_LEVEL_THREAD","SCOPE_LEVEL_USER"],"default":"SCOPE_LEVEL_UNSPECIFIED","description":"The scope level for a memory block's content storage.\n\n - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT).\n - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads.\n - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content.\n - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content,\nwhich follows them across all of their threads with the agent and is\ninvisible to other users. Only kinds whose allowed_scopes include it\n(or list no restriction) accept it."},"agentsV1ToolRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool identifier (hash of the original tool name).","readOnly":true},"name":{"type":"string","description":"The tool name (may be adapted name if adapters are applied).","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted.","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations).","readOnly":true}},"description":"Lightweight tool reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits parameters_schema to keep responses lightweight."},"agentsV1ModelInfo":{"type":"object","properties":{"model_id":{"type":"string","description":"Model identifier (e.g., \"gpt-4o\", \"claude-3-opus\").","readOnly":true},"max_context_tokens":{"type":"integer","format":"int64","description":"Maximum context length in tokens.","readOnly":true},"max_output_tokens":{"type":"integer","format":"int64","description":"Maximum output tokens.","readOnly":true},"supports_vision":{"type":"boolean","description":"Whether the model supports vision/images.","readOnly":true},"supports_tools":{"type":"boolean","description":"Whether the model supports tool/function calling.","readOnly":true},"supports_structured_output":{"type":"boolean","description":"Whether the model supports structured output (JSON mode).","readOnly":true},"supports_streaming":{"type":"boolean","description":"Whether the model supports streaming responses.","readOnly":true},"supports_reasoning":{"type":"boolean","description":"Whether the model supports reasoning (chain-of-thought).","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"GPT-4o\", \"Claude Sonnet 4.5\").","readOnly":true},"family":{"type":"string","description":"Model family grouping (e.g., \"gpt-4o\", \"claude-4.5\", \"qwen2\").","readOnly":true},"license":{"type":"string","description":"License information (e.g., for open-weight models).","readOnly":true},"parameter_count":{"type":"string","format":"uint64","description":"Number of model parameters.","readOnly":true},"quantization":{"type":"string","description":"Quantization level (e.g., \"Q4_K_M\", \"Q8_0\").","readOnly":true},"supports_documents":{"type":"boolean","description":"Whether the model supports document inputs (PDFs, text files).","readOnly":true},"max_inline_artifact_bytes":{"type":"string","format":"uint64","description":"Maximum size of a single tool result that can be inlined into a\ngeneration request, in raw bytes. Already accounts for base64 expansion\nand a safety margin for request overhead.","readOnly":true},"deprecated":{"type":"boolean","description":"Whether the model is deprecated: still usable, but slated for retirement.","readOnly":true},"retired":{"type":"boolean","description":"Whether the model is retired: loadable (so existing threads/agents don't\nbreak) but generation is refused.","readOnly":true},"replacement_model":{"type":"string","description":"Recommended replacement model id when deprecated or retired.","readOnly":true},"pricing":{"$ref":"#/components/schemas/agentsV1ModelPricing"}},"description":"Information about a model and its capabilities."},"agentsV1ModelPricing":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DatedRates"},"description":"Effective-dated rate rows. Windows should not overlap; if they do, the\nearliest-starting matching row wins so the outcome is deterministic.","readOnly":true}},"description":"Complete pricing knowledge for one model: its effective-dated rate rows.\n\nAn empty `rows` list is a valid \"priced at zero\" card for local models —\ndistinct from a model carrying no `ModelPricing` at all, which means its\ncost is unknown, not free."},"agentsV1DatedRates":{"type":"object","properties":{"effective_from":{"type":"string","format":"date-time","description":"Inclusive start of this row's validity. Absent = open-ended past.","readOnly":true},"effective_until":{"type":"string","format":"date-time","description":"Exclusive end of this row's validity. Absent = open-ended future.","readOnly":true},"base":{"$ref":"#/components/schemas/agentsV1RateCard"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1TierRates"},"description":"Long-context tiers: token-threshold bands above `base`, ascending by\n`threshold_tokens`. Empty = flat pricing. A request's total prompt size\nselects the highest tier whose threshold it reaches, or `base` below\nevery threshold.","readOnly":true}},"description":"One effective-dated pricing row: the rates in force during a validity\nwindow. A model whose price changes on a schedule carries several rows\ndiffering only in rates and effective bounds."},"agentsV1RateCard":{"type":"object","properties":{"input_per_mtok":{"type":"number","format":"double","description":"Fresh (uncached) input, USD per million tokens.","readOnly":true},"output_per_mtok":{"type":"number","format":"double","description":"Output, USD per million tokens. Includes reasoning/thinking tokens.","readOnly":true},"cache_read_per_mtok":{"type":"number","format":"double","description":"Tokens served from cache, USD per million tokens.","readOnly":true},"cache_write_per_mtok":{"type":"number","format":"double","description":"Cache writes at any TTL, USD per million tokens — for providers with a\nsingle write rate regardless of TTL.","readOnly":true},"cache_write_by_ttl":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWriteRate"},"description":"Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`.","readOnly":true}},"description":"One complete set of USD-per-million-token rates. A missing cache rate is\nnot zero — it means the dimension is unpublished, and cost computation\nfalls back loudly (billed at the fresh-input rate, flagged estimated)."},"agentsV1CacheWriteRate":{"type":"object","properties":{"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket,\n3600 for a 1-hour bucket).","readOnly":true},"per_mtok":{"type":"number","format":"double","description":"USD per million tokens written into this bucket.","readOnly":true}},"description":"USD rate for cache writes at one specific TTL bucket."},"agentsV1TierRates":{"type":"object","properties":{"threshold_tokens":{"type":"integer","format":"int64","description":"Prompt-size threshold (total prompt tokens: fresh + cache read + cache\nwrite) at which these rates activate.","readOnly":true},"card":{"$ref":"#/components/schemas/agentsV1RateCard"}},"description":"One long-context tier band: requests whose total prompt tokens meet or\nexceed `threshold_tokens` (and fall below the next tier's threshold, when\none exists) bill the entire request — every class, input and output — at\n`card` instead of the base card."},"agentsV1ContextSummary":{"type":"object","properties":{"fixed_tokens":{"type":"integer","format":"int64","description":"Tokens used by fixed context (immutable memory + tools).","readOnly":true},"volatile_tokens":{"type":"integer","format":"int64","description":"Tokens used by volatile context (mutable memory).","readOnly":true},"compactable_tokens":{"type":"integer","format":"int64","description":"Tokens used by compactable context (conversation).","readOnly":true},"total_used_tokens":{"type":"integer","format":"int64","description":"Total tokens currently in use.","readOnly":true},"available_tokens":{"type":"integer","format":"int64","description":"Tokens available before hitting the context limit.","readOnly":true}},"description":"Summary of token usage by category."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/context":{"get":{"summary":"Get Thread Context (Quill2, automation)","description":"Gets thread context information including all context items with token counts.\n\nReturns a unified view of all items contributing to the context window:\n- Memory blocks (fixed and volatile)\n- Enabled tools (fixed)\n- Conversation history (compactable)\n\nEach item includes its token count for context budget management.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetThreadContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetThreadContextResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"The thread ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events (Quill2, automation)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Quill2, automation)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message And Wait (Quill2, automation)

> Sends a message and streams back response events synchronously.\
> \
> This RPC adds user input to the specified thread and returns a stream\
> of events representing the assistant's response. Events include output text,\
> tool calls, and completion metadata.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`SendMessageAndWait\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageSyncBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message and stream response events synchronously."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/events":{"post":{"summary":"Send Message And Wait (Quill2, automation)","description":"Sends a message and streams back response events synchronously.\n\nThis RPC adds user input to the specified thread and returns a stream\nof events representing the assistant's response. Events include output text,\ntool calls, and completion metadata.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`.","operationId":"AutomationQuill2SendMessageAndWait","responses":{"200":{"description":"A successful response.(streaming responses)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/agentsV1Event"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"Stream result of v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageSyncBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Set Thread Feedback (Quill2, automation)

> Sets feedback (like/dislike) for a generation response.\
> \
> Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\
> Setting the same feedback that already exists is a no-op.\
> Use FEEDBACK\_TYPE\_UNSPECIFIED to clear existing feedback.\
> \
> Feedback is stored with the thread and is purely for analytics/UI purposes.\
> It is not visible to the LLM.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`SetThreadFeedback\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SetFeedbackResponse":{"type":"object","properties":{"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"previous_feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Response for setting feedback on a generation."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSetFeedbackBody":{"type":"object","properties":{"generation_id":{"type":"string","description":"Required. The generation ID (from GenerationComplete.id)."},"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Request to set feedback for a generation response."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/feedback":{"post":{"summary":"Set Thread Feedback (Quill2, automation)","description":"Sets feedback (like/dislike) for a generation response.\n\nFeedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\nSetting the same feedback that already exists is a no-op.\nUse FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback.\n\nFeedback is stored with the thread and is purely for analytics/UI purposes.\nIt is not visible to the LLM.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`.","operationId":"AutomationQuill2SetThreadFeedback","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SetFeedbackResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread containing the generation.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSetFeedbackBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Message (Quill2, automation)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/input":{"post":{"summary":"Send Message (Quill2, automation)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"AutomationQuill2SendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Active Plan (Quill2, automation)

> Gets the active plan snapshot for a thread (with per-step\
> statuses). Distinct from \`GET /plan\`, which returns the template.\
> \
> Returns NOT\_FOUND if no active plan exists.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`GetActivePlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active":{"get":{"summary":"Get Active Plan (Quill2, automation)","description":"Gets the active plan snapshot for a thread (with per-step\nstatuses). Distinct from `GET /plan`, which returns the template.\n\nReturns NOT_FOUND if no active plan exists.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `GetActivePlan` on `/agents/{agent_id}`.","operationId":"AutomationQuill2GetActivePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to get the plan for.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Mark Plan Step (Quill2, automation)

> Marks a step on the active plan as completed or failed.\
> \
> Returns NOT\_FOUND if no active plan exists or the phase/step index\
> is invalid.\
> Returns FAILED\_PRECONDITION if the thread is currently generating,\
> the step is not in the active phase, or the step is already\
> resolved.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`MarkPlanStep\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceMarkStepBody":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Optional reason for failure (only used when status is STEP_STATUS_FAILED)."}},"description":"Request to mark a step's status in a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active/phases/{phase_index}/steps/{step_index}:mark":{"post":{"summary":"Mark Plan Step (Quill2, automation)","description":"Marks a step on the active plan as completed or failed.\n\nReturns NOT_FOUND if no active plan exists or the phase/step index\nis invalid.\nReturns FAILED_PRECONDITION if the thread is currently generating,\nthe step is not in the active phase, or the step is already\nresolved.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `MarkPlanStep` on `/agents/{agent_id}`.","operationId":"AutomationQuill2MarkPlanStep","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to modify.","in":"path","required":true,"schema":{"type":"string"}},{"name":"phase_index","description":"Required. 1-indexed phase position.","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"step_index","description":"Required. 1-indexed step position.","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceMarkStepBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Deactivate Plan (Quill2, automation)

> Deactivates the active plan. The snapshot is kept (flagged\
> inactive) for status carry-over on the next activation.\
> \
> No generation guard — always allowed.\
> Returns NOT\_FOUND if no active plan exists.\
> Returns FAILED\_PRECONDITION if the plan is not active.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`DeactivatePlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceDeactivatePlanBody":{"type":"object","properties":{},"description":"Request to deactivate a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active:deactivate":{"post":{"summary":"Deactivate Plan (Quill2, automation)","description":"Deactivates the active plan. The snapshot is kept (flagged\ninactive) for status carry-over on the next activation.\n\nNo generation guard — always allowed.\nReturns NOT_FOUND if no active plan exists.\nReturns FAILED_PRECONDITION if the plan is not active.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `DeactivatePlan` on `/agents/{agent_id}`.","operationId":"AutomationQuill2DeactivatePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to deactivate.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceDeactivatePlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Reset Plan (Quill2, automation)

> Resets all step statuses on the active plan back to pending.\
> \
> Clears all step statuses and failure reasons. If the plan is\
> active, it is deactivated first before resetting.\
> Returns NOT\_FOUND if no active plan exists.\
> Returns FAILED\_PRECONDITION if the thread is currently generating.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`ResetPlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceResetPlanBody":{"type":"object","properties":{},"description":"Request to reset all steps in a thread's plan back to pending."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan/active:reset":{"post":{"summary":"Reset Plan (Quill2, automation)","description":"Resets all step statuses on the active plan back to pending.\n\nClears all step statuses and failure reasons. If the plan is\nactive, it is deactivated first before resetting.\nReturns NOT_FOUND if no active plan exists.\nReturns FAILED_PRECONDITION if the thread is currently generating.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `ResetPlan` on `/agents/{agent_id}`.","operationId":"AutomationQuill2ResetPlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to reset.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceResetPlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Activate Plan (Quill2, automation)

> Activates the plan for a thread. Snapshots the current template\
> plan and carries over statuses from any previous snapshot by id.\
> \
> Returns NOT\_FOUND if no plan template exists.\
> Returns FAILED\_PRECONDITION if the thread is currently generating,\
> the plan is already active, or the template has no phases.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`ActivatePlan\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Plan":{"type":"object","properties":{"name":{"type":"string","description":"Name of the plan."},"description":{"type":"string","description":"Description of the plan."},"active":{"type":"boolean","description":"Whether the plan is currently active."},"phases":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Phase"},"description":"Ordered list of phases in this plan."}},"description":"A structured plan with phases and steps."},"agentsV1Phase":{"type":"object","properties":{"name":{"type":"string","description":"Name of the phase."},"description":{"type":"string","description":"Description of the phase."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Step"},"description":"Ordered list of steps in this phase."}},"description":"A phase containing ordered steps."},"agentsV1Step":{"type":"object","properties":{"name":{"type":"string","description":"Name of the step."},"description":{"type":"string","description":"Description of what needs to be done."},"acceptance_criteria":{"type":"string","description":"Criteria for determining when the step is complete."},"status":{"$ref":"#/components/schemas/agentsV1StepStatus"},"failure_reason":{"type":"string","description":"Reason for failure (only set when status is FAILED)."}},"description":"A single step within a phase."},"agentsV1StepStatus":{"type":"string","enum":["STEP_STATUS_UNSPECIFIED","STEP_STATUS_PENDING","STEP_STATUS_COMPLETED","STEP_STATUS_FAILED","STEP_STATUS_SKIPPED"],"default":"STEP_STATUS_UNSPECIFIED","description":"Status of a plan step.\n\n - STEP_STATUS_UNSPECIFIED: Unspecified step status.\n - STEP_STATUS_PENDING: Step has not started yet.\n - STEP_STATUS_COMPLETED: Step completed successfully.\n - STEP_STATUS_FAILED: Step failed.\n - STEP_STATUS_SKIPPED: Step was skipped."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceActivatePlanBody":{"type":"object","properties":{},"description":"Request to activate a thread's plan."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/plan:activate":{"post":{"summary":"Activate Plan (Quill2, automation)","description":"Activates the plan for a thread. Snapshots the current template\nplan and carries over statuses from any previous snapshot by id.\n\nReturns NOT_FOUND if no plan template exists.\nReturns FAILED_PRECONDITION if the thread is currently generating,\nthe plan is already active, or the template has no phases.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `ActivatePlan` on `/agents/{agent_id}`.","operationId":"AutomationQuill2ActivatePlan","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Plan"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread whose plan to activate.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceActivatePlanBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Quill2, automation)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Quill2, automation)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"AutomationQuill2StreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## List Sub Agents (Quill2, automation)

> Lists sub-agents configured for a thread.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`ListSubAgents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListSubAgentsResponse":{"type":"object","properties":{"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"The sub-agents configured for the thread."},"is_customized":{"type":"boolean","description":"Whether this represents a per-thread customization (vs inherited from agent)."}},"description":"Response message for ListSubAgents."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/sub-agents":{"get":{"summary":"List Sub Agents (Quill2, automation)","description":"Lists sub-agents configured for a thread.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`.","operationId":"AutomationQuill2ListSubAgents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListSubAgentsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread whose sub-agents to list.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Tool Call (Quill2, automation)

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`SendToolCall\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call (Quill2, automation)","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `SendToolCall` on `/agents/{agent_id}`.","operationId":"AutomationQuill2SendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result (Quill2, automation)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Quill2, automation)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"AutomationQuill2SendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File (Quill2, automation)

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`UploadThreadFile\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File (Quill2, automation)","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`.","operationId":"AutomationQuill2UploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Compact Thread (Quill2, automation)

> Starts context compaction for a thread.\
> \
> Compaction summarizes conversation history to reduce context size while\
> preserving essential information. This RPC emits a CompactStart event\
> and returns the compact\_id for tracking.\
> \
> The actual compaction is performed asynchronously. Once complete, a\
> CompactComplete event with the summary content should be added to the\
> thread using the returned compact\_id.\
> \
> While compaction is in progress (CompactStart without CompactComplete),\
> the UI should block user input.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`CompactThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StartCompactionResponse":{"type":"object","properties":{"compact_id":{"type":"string","description":"The unique ID assigned to this compaction operation."}},"description":"Response for starting context compaction."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStartCompactionBody":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"Optional. The event ID from which to start compaction.\nEvents from this ID onwards (inclusive) will be compacted.\nIf not specified, the entire conversation is compacted."}},"description":"Request to start context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. A CompactStart event is emitted immediately,\nand an external compaction process should later emit CompactComplete with the\nsummary."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:compact":{"post":{"summary":"Compact Thread (Quill2, automation)","description":"Starts context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. This RPC emits a CompactStart event\nand returns the compact_id for tracking.\n\nThe actual compaction is performed asynchronously. Once complete, a\nCompactComplete event with the summary content should be added to the\nthread using the returned compact_id.\n\nWhile compaction is in progress (CompactStart without CompactComplete),\nthe UI should block user input.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `CompactThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2CompactThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StartCompactionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to compact.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStartCompactionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Fork Thread (Quill2, automation)

> Forks (duplicates) a thread with all its data.\
> \
> Creates a new thread that is a complete copy of the source thread,\
> including events, feedback, memory customizations, scratchpad, plan,\
> and template config customizations.\
> Returns FAILED\_PRECONDITION if the source thread is currently generating.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`ForkThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceForkThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the new thread. Defaults to \"Fork of {source_title}\"."}},"description":"Request message for ForkThread (duplicate a thread with all its data)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:fork":{"post":{"summary":"Fork Thread (Quill2, automation)","description":"Forks (duplicates) a thread with all its data.\n\nCreates a new thread that is a complete copy of the source thread,\nincluding events, feedback, memory customizations, scratchpad, plan,\nand template config customizations.\nReturns FAILED_PRECONDITION if the source thread is currently generating.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `ForkThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2ForkThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The source thread to fork.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceForkThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stop Thread (Quill2, automation)

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`StopThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread (Quill2, automation)","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `StopThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2StopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread (Quill2, automation)

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.\
> \
> Targets the built-in \`quill2\` agent in the automation scope; the generic form is \`WakeThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/agents/quill2/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread (Quill2, automation)","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.\n\nTargets the built-in `quill2` agent in the automation scope; the generic form is `WakeThread` on `/agents/{agent_id}`.","operationId":"AutomationQuill2WakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Threads (Astral Lite, run)

> Lists all threads for an agent.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads":{"get":{"summary":"List Threads (Astral Lite, run)","description":"Lists all threads for an agent.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"RunAstralLiteListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Astral Lite, run)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads":{"post":{"summary":"Create Thread (Astral Lite, run)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread (Astral Lite, run)

> Gets a thread by ID.\
> \
> Returns thread metadata and event count without loading the full event history.\
> Returns NOT\_FOUND if the thread doesn't exist.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`GetThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}":{"get":{"summary":"Get Thread (Astral Lite, run)","description":"Gets a thread by ID.\n\nReturns thread metadata and event count without loading the full event history.\nReturns NOT_FOUND if the thread doesn't exist.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `GetThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteGetThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Thread (Astral Lite, run)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Astral Lite, run)","description":"Deletes a thread and all its events.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteDeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Thread (Astral Lite, run)

> Updates a thread's title and/or description.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`UpdateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional new title for the thread."},"description":{"type":"string","description":"Optional new description for the thread."}},"description":"Request to update a thread's metadata."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}":{"patch":{"summary":"Update Thread (Astral Lite, run)","description":"Updates a thread's title and/or description.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `UpdateThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteUpdateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread Context (Astral Lite, run)

> Gets thread context information including all context items with token counts.\
> \
> Returns a unified view of all items contributing to the context window:\
> \- Memory blocks (fixed and volatile)\
> \- Enabled tools (fixed)\
> \- Conversation history (compactable)\
> \
> Each item includes its token count for context budget management.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`GetThreadContext\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetThreadContextResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ContextItem"},"description":"List of context items contributing to the thread's context window.","readOnly":true},"model_info":{"$ref":"#/components/schemas/agentsV1ModelInfo"},"summary":{"$ref":"#/components/schemas/agentsV1ContextSummary"},"auto_compact_tokens":{"type":"integer","format":"int64","description":"Prompt token count at which the next completed turn triggers\nauto-compaction.\n\nAbsent when no compactor is configured, in which case auto-compaction\nnever fires, or when the model does not report a context window.","readOnly":true}},"description":"Response containing thread context information."},"agentsV1ContextItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the context item.","readOnly":true},"label":{"type":"string","description":"Human-readable label for display.","readOnly":true},"token_count":{"type":"integer","format":"int64","description":"Number of tokens this item consumes.","readOnly":true},"category":{"$ref":"#/components/schemas/agentsV1ContextCategory"},"memory_block":{"$ref":"#/components/schemas/agentsV1MemoryBlockRef"},"tool":{"$ref":"#/components/schemas/agentsV1ToolRef"}},"description":"A single item contributing to the thread's context window."},"agentsV1ContextCategory":{"type":"string","enum":["CONTEXT_CATEGORY_UNSPECIFIED","CONTEXT_CATEGORY_FIXED","CONTEXT_CATEGORY_VOLATILE","CONTEXT_CATEGORY_COMPACTABLE"],"default":"CONTEXT_CATEGORY_UNSPECIFIED","description":"Category of context items for token budget management.\n\n - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category.\n - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools).\n - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks).\n - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history)."},"agentsV1MemoryBlockRef":{"type":"object","properties":{"block_id":{"type":"string","description":"The unique block identifier (deterministic hash of block name).","readOnly":true},"type":{"type":"string","description":"The block type (e.g., \"text\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the block type.","readOnly":true},"description":{"type":"string","description":"Description of the memory block.","readOnly":true},"scope":{"$ref":"#/components/schemas/agentsV1ScopeLevel"},"mutable":{"type":"boolean","description":"Whether the block is mutable.","readOnly":true}},"description":"Lightweight memory block reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits content and config to keep responses lightweight."},"agentsV1ScopeLevel":{"type":"string","enum":["SCOPE_LEVEL_UNSPECIFIED","SCOPE_LEVEL_AGENT","SCOPE_LEVEL_THREAD","SCOPE_LEVEL_USER"],"default":"SCOPE_LEVEL_UNSPECIFIED","description":"The scope level for a memory block's content storage.\n\n - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT).\n - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads.\n - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content.\n - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content,\nwhich follows them across all of their threads with the agent and is\ninvisible to other users. Only kinds whose allowed_scopes include it\n(or list no restriction) accept it."},"agentsV1ToolRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool identifier (hash of the original tool name).","readOnly":true},"name":{"type":"string","description":"The tool name (may be adapted name if adapters are applied).","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted.","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations).","readOnly":true}},"description":"Lightweight tool reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits parameters_schema to keep responses lightweight."},"agentsV1ModelInfo":{"type":"object","properties":{"model_id":{"type":"string","description":"Model identifier (e.g., \"gpt-4o\", \"claude-3-opus\").","readOnly":true},"max_context_tokens":{"type":"integer","format":"int64","description":"Maximum context length in tokens.","readOnly":true},"max_output_tokens":{"type":"integer","format":"int64","description":"Maximum output tokens.","readOnly":true},"supports_vision":{"type":"boolean","description":"Whether the model supports vision/images.","readOnly":true},"supports_tools":{"type":"boolean","description":"Whether the model supports tool/function calling.","readOnly":true},"supports_structured_output":{"type":"boolean","description":"Whether the model supports structured output (JSON mode).","readOnly":true},"supports_streaming":{"type":"boolean","description":"Whether the model supports streaming responses.","readOnly":true},"supports_reasoning":{"type":"boolean","description":"Whether the model supports reasoning (chain-of-thought).","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"GPT-4o\", \"Claude Sonnet 4.5\").","readOnly":true},"family":{"type":"string","description":"Model family grouping (e.g., \"gpt-4o\", \"claude-4.5\", \"qwen2\").","readOnly":true},"license":{"type":"string","description":"License information (e.g., for open-weight models).","readOnly":true},"parameter_count":{"type":"string","format":"uint64","description":"Number of model parameters.","readOnly":true},"quantization":{"type":"string","description":"Quantization level (e.g., \"Q4_K_M\", \"Q8_0\").","readOnly":true},"supports_documents":{"type":"boolean","description":"Whether the model supports document inputs (PDFs, text files).","readOnly":true},"max_inline_artifact_bytes":{"type":"string","format":"uint64","description":"Maximum size of a single tool result that can be inlined into a\ngeneration request, in raw bytes. Already accounts for base64 expansion\nand a safety margin for request overhead.","readOnly":true},"deprecated":{"type":"boolean","description":"Whether the model is deprecated: still usable, but slated for retirement.","readOnly":true},"retired":{"type":"boolean","description":"Whether the model is retired: loadable (so existing threads/agents don't\nbreak) but generation is refused.","readOnly":true},"replacement_model":{"type":"string","description":"Recommended replacement model id when deprecated or retired.","readOnly":true},"pricing":{"$ref":"#/components/schemas/agentsV1ModelPricing"}},"description":"Information about a model and its capabilities."},"agentsV1ModelPricing":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DatedRates"},"description":"Effective-dated rate rows. Windows should not overlap; if they do, the\nearliest-starting matching row wins so the outcome is deterministic.","readOnly":true}},"description":"Complete pricing knowledge for one model: its effective-dated rate rows.\n\nAn empty `rows` list is a valid \"priced at zero\" card for local models —\ndistinct from a model carrying no `ModelPricing` at all, which means its\ncost is unknown, not free."},"agentsV1DatedRates":{"type":"object","properties":{"effective_from":{"type":"string","format":"date-time","description":"Inclusive start of this row's validity. Absent = open-ended past.","readOnly":true},"effective_until":{"type":"string","format":"date-time","description":"Exclusive end of this row's validity. Absent = open-ended future.","readOnly":true},"base":{"$ref":"#/components/schemas/agentsV1RateCard"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1TierRates"},"description":"Long-context tiers: token-threshold bands above `base`, ascending by\n`threshold_tokens`. Empty = flat pricing. A request's total prompt size\nselects the highest tier whose threshold it reaches, or `base` below\nevery threshold.","readOnly":true}},"description":"One effective-dated pricing row: the rates in force during a validity\nwindow. A model whose price changes on a schedule carries several rows\ndiffering only in rates and effective bounds."},"agentsV1RateCard":{"type":"object","properties":{"input_per_mtok":{"type":"number","format":"double","description":"Fresh (uncached) input, USD per million tokens.","readOnly":true},"output_per_mtok":{"type":"number","format":"double","description":"Output, USD per million tokens. Includes reasoning/thinking tokens.","readOnly":true},"cache_read_per_mtok":{"type":"number","format":"double","description":"Tokens served from cache, USD per million tokens.","readOnly":true},"cache_write_per_mtok":{"type":"number","format":"double","description":"Cache writes at any TTL, USD per million tokens — for providers with a\nsingle write rate regardless of TTL.","readOnly":true},"cache_write_by_ttl":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWriteRate"},"description":"Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`.","readOnly":true}},"description":"One complete set of USD-per-million-token rates. A missing cache rate is\nnot zero — it means the dimension is unpublished, and cost computation\nfalls back loudly (billed at the fresh-input rate, flagged estimated)."},"agentsV1CacheWriteRate":{"type":"object","properties":{"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket,\n3600 for a 1-hour bucket).","readOnly":true},"per_mtok":{"type":"number","format":"double","description":"USD per million tokens written into this bucket.","readOnly":true}},"description":"USD rate for cache writes at one specific TTL bucket."},"agentsV1TierRates":{"type":"object","properties":{"threshold_tokens":{"type":"integer","format":"int64","description":"Prompt-size threshold (total prompt tokens: fresh + cache read + cache\nwrite) at which these rates activate.","readOnly":true},"card":{"$ref":"#/components/schemas/agentsV1RateCard"}},"description":"One long-context tier band: requests whose total prompt tokens meet or\nexceed `threshold_tokens` (and fall below the next tier's threshold, when\none exists) bill the entire request — every class, input and output — at\n`card` instead of the base card."},"agentsV1ContextSummary":{"type":"object","properties":{"fixed_tokens":{"type":"integer","format":"int64","description":"Tokens used by fixed context (immutable memory + tools).","readOnly":true},"volatile_tokens":{"type":"integer","format":"int64","description":"Tokens used by volatile context (mutable memory).","readOnly":true},"compactable_tokens":{"type":"integer","format":"int64","description":"Tokens used by compactable context (conversation).","readOnly":true},"total_used_tokens":{"type":"integer","format":"int64","description":"Total tokens currently in use.","readOnly":true},"available_tokens":{"type":"integer","format":"int64","description":"Tokens available before hitting the context limit.","readOnly":true}},"description":"Summary of token usage by category."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/context":{"get":{"summary":"Get Thread Context (Astral Lite, run)","description":"Gets thread context information including all context items with token counts.\n\nReturns a unified view of all items contributing to the context window:\n- Memory blocks (fixed and volatile)\n- Enabled tools (fixed)\n- Conversation history (compactable)\n\nEach item includes its token count for context budget management.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`.","operationId":"RunAstralLiteGetThreadContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetThreadContextResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"The thread ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events (Astral Lite, run)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Astral Lite, run)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"RunAstralLiteGetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message And Wait (Astral Lite, run)

> Sends a message and streams back response events synchronously.\
> \
> This RPC adds user input to the specified thread and returns a stream\
> of events representing the assistant's response. Events include output text,\
> tool calls, and completion metadata.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`SendMessageAndWait\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageSyncBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message and stream response events synchronously."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/events":{"post":{"summary":"Send Message And Wait (Astral Lite, run)","description":"Sends a message and streams back response events synchronously.\n\nThis RPC adds user input to the specified thread and returns a stream\nof events representing the assistant's response. Events include output text,\ntool calls, and completion metadata.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`.","operationId":"RunAstralLiteSendMessageAndWait","responses":{"200":{"description":"A successful response.(streaming responses)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/agentsV1Event"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"Stream result of v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageSyncBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Set Thread Feedback (Astral Lite, run)

> Sets feedback (like/dislike) for a generation response.\
> \
> Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\
> Setting the same feedback that already exists is a no-op.\
> Use FEEDBACK\_TYPE\_UNSPECIFIED to clear existing feedback.\
> \
> Feedback is stored with the thread and is purely for analytics/UI purposes.\
> It is not visible to the LLM.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`SetThreadFeedback\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SetFeedbackResponse":{"type":"object","properties":{"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"previous_feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Response for setting feedback on a generation."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSetFeedbackBody":{"type":"object","properties":{"generation_id":{"type":"string","description":"Required. The generation ID (from GenerationComplete.id)."},"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Request to set feedback for a generation response."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/feedback":{"post":{"summary":"Set Thread Feedback (Astral Lite, run)","description":"Sets feedback (like/dislike) for a generation response.\n\nFeedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\nSetting the same feedback that already exists is a no-op.\nUse FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback.\n\nFeedback is stored with the thread and is purely for analytics/UI purposes.\nIt is not visible to the LLM.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`.","operationId":"RunAstralLiteSetThreadFeedback","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SetFeedbackResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread containing the generation.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSetFeedbackBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Message (Astral Lite, run)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/input":{"post":{"summary":"Send Message (Astral Lite, run)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"RunAstralLiteSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Astral Lite, run)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Astral Lite, run)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"RunAstralLiteStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## List Sub Agents (Astral Lite, run)

> Lists sub-agents configured for a thread.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`ListSubAgents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListSubAgentsResponse":{"type":"object","properties":{"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"The sub-agents configured for the thread."},"is_customized":{"type":"boolean","description":"Whether this represents a per-thread customization (vs inherited from agent)."}},"description":"Response message for ListSubAgents."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/sub-agents":{"get":{"summary":"List Sub Agents (Astral Lite, run)","description":"Lists sub-agents configured for a thread.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`.","operationId":"RunAstralLiteListSubAgents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListSubAgentsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread whose sub-agents to list.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Tool Call (Astral Lite, run)

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`SendToolCall\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call (Astral Lite, run)","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `SendToolCall` on `/agents/{agent_id}`.","operationId":"RunAstralLiteSendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result (Astral Lite, run)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Astral Lite, run)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"RunAstralLiteSendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File (Astral Lite, run)

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`UploadThreadFile\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File (Astral Lite, run)","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`.","operationId":"RunAstralLiteUploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Compact Thread (Astral Lite, run)

> Starts context compaction for a thread.\
> \
> Compaction summarizes conversation history to reduce context size while\
> preserving essential information. This RPC emits a CompactStart event\
> and returns the compact\_id for tracking.\
> \
> The actual compaction is performed asynchronously. Once complete, a\
> CompactComplete event with the summary content should be added to the\
> thread using the returned compact\_id.\
> \
> While compaction is in progress (CompactStart without CompactComplete),\
> the UI should block user input.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`CompactThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StartCompactionResponse":{"type":"object","properties":{"compact_id":{"type":"string","description":"The unique ID assigned to this compaction operation."}},"description":"Response for starting context compaction."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStartCompactionBody":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"Optional. The event ID from which to start compaction.\nEvents from this ID onwards (inclusive) will be compacted.\nIf not specified, the entire conversation is compacted."}},"description":"Request to start context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. A CompactStart event is emitted immediately,\nand an external compaction process should later emit CompactComplete with the\nsummary."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:compact":{"post":{"summary":"Compact Thread (Astral Lite, run)","description":"Starts context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. This RPC emits a CompactStart event\nand returns the compact_id for tracking.\n\nThe actual compaction is performed asynchronously. Once complete, a\nCompactComplete event with the summary content should be added to the\nthread using the returned compact_id.\n\nWhile compaction is in progress (CompactStart without CompactComplete),\nthe UI should block user input.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `CompactThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteCompactThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StartCompactionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to compact.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStartCompactionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Fork Thread (Astral Lite, run)

> Forks (duplicates) a thread with all its data.\
> \
> Creates a new thread that is a complete copy of the source thread,\
> including events, feedback, memory customizations, scratchpad, plan,\
> and template config customizations.\
> Returns FAILED\_PRECONDITION if the source thread is currently generating.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`ForkThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceForkThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the new thread. Defaults to \"Fork of {source_title}\"."}},"description":"Request message for ForkThread (duplicate a thread with all its data)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:fork":{"post":{"summary":"Fork Thread (Astral Lite, run)","description":"Forks (duplicates) a thread with all its data.\n\nCreates a new thread that is a complete copy of the source thread,\nincluding events, feedback, memory customizations, scratchpad, plan,\nand template config customizations.\nReturns FAILED_PRECONDITION if the source thread is currently generating.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `ForkThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteForkThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The source thread to fork.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceForkThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stop Thread (Astral Lite, run)

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`StopThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread (Astral Lite, run)","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `StopThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteStopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread (Astral Lite, run)

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.\
> \
> Targets the built-in \`astral-lite\` agent in the run scope; the generic form is \`WakeThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral-lite/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread (Astral Lite, run)","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.\n\nTargets the built-in `astral-lite` agent in the run scope; the generic form is `WakeThread` on `/agents/{agent_id}`.","operationId":"RunAstralLiteWakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Threads (Astral2, run)

> Lists all threads for an agent.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads":{"get":{"summary":"List Threads (Astral2, run)","description":"Lists all threads for an agent.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"RunAstral2ListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Astral2, run)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads":{"post":{"summary":"Create Thread (Astral2, run)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"RunAstral2CreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread (Astral2, run)

> Gets a thread by ID.\
> \
> Returns thread metadata and event count without loading the full event history.\
> Returns NOT\_FOUND if the thread doesn't exist.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`GetThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}":{"get":{"summary":"Get Thread (Astral2, run)","description":"Gets a thread by ID.\n\nReturns thread metadata and event count without loading the full event history.\nReturns NOT_FOUND if the thread doesn't exist.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `GetThread` on `/agents/{agent_id}`.","operationId":"RunAstral2GetThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Delete Thread (Astral2, run)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Astral2, run)","description":"Deletes a thread and all its events.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"RunAstral2DeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Update Thread (Astral2, run)

> Updates a thread's title and/or description.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`UpdateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceUpdateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional new title for the thread."},"description":{"type":"string","description":"Optional new description for the thread."}},"description":"Request to update a thread's metadata."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}":{"patch":{"summary":"Update Thread (Astral2, run)","description":"Updates a thread's title and/or description.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `UpdateThread` on `/agents/{agent_id}`.","operationId":"RunAstral2UpdateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceUpdateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Get Thread Context (Astral2, run)

> Gets thread context information including all context items with token counts.\
> \
> Returns a unified view of all items contributing to the context window:\
> \- Memory blocks (fixed and volatile)\
> \- Enabled tools (fixed)\
> \- Conversation history (compactable)\
> \
> Each item includes its token count for context budget management.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`GetThreadContext\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetThreadContextResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ContextItem"},"description":"List of context items contributing to the thread's context window.","readOnly":true},"model_info":{"$ref":"#/components/schemas/agentsV1ModelInfo"},"summary":{"$ref":"#/components/schemas/agentsV1ContextSummary"},"auto_compact_tokens":{"type":"integer","format":"int64","description":"Prompt token count at which the next completed turn triggers\nauto-compaction.\n\nAbsent when no compactor is configured, in which case auto-compaction\nnever fires, or when the model does not report a context window.","readOnly":true}},"description":"Response containing thread context information."},"agentsV1ContextItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the context item.","readOnly":true},"label":{"type":"string","description":"Human-readable label for display.","readOnly":true},"token_count":{"type":"integer","format":"int64","description":"Number of tokens this item consumes.","readOnly":true},"category":{"$ref":"#/components/schemas/agentsV1ContextCategory"},"memory_block":{"$ref":"#/components/schemas/agentsV1MemoryBlockRef"},"tool":{"$ref":"#/components/schemas/agentsV1ToolRef"}},"description":"A single item contributing to the thread's context window."},"agentsV1ContextCategory":{"type":"string","enum":["CONTEXT_CATEGORY_UNSPECIFIED","CONTEXT_CATEGORY_FIXED","CONTEXT_CATEGORY_VOLATILE","CONTEXT_CATEGORY_COMPACTABLE"],"default":"CONTEXT_CATEGORY_UNSPECIFIED","description":"Category of context items for token budget management.\n\n - CONTEXT_CATEGORY_UNSPECIFIED: Unspecified category.\n - CONTEXT_CATEGORY_FIXED: Fixed context that cannot be modified (agent-scoped immutable memory + tools).\n - CONTEXT_CATEGORY_VOLATILE: Volatile context that can be modified (mutable memory blocks).\n - CONTEXT_CATEGORY_COMPACTABLE: Compactable context that can be summarized (conversation history)."},"agentsV1MemoryBlockRef":{"type":"object","properties":{"block_id":{"type":"string","description":"The unique block identifier (deterministic hash of block name).","readOnly":true},"type":{"type":"string","description":"The block type (e.g., \"text\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the block type.","readOnly":true},"description":{"type":"string","description":"Description of the memory block.","readOnly":true},"scope":{"$ref":"#/components/schemas/agentsV1ScopeLevel"},"mutable":{"type":"boolean","description":"Whether the block is mutable.","readOnly":true}},"description":"Lightweight memory block reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits content and config to keep responses lightweight."},"agentsV1ScopeLevel":{"type":"string","enum":["SCOPE_LEVEL_UNSPECIFIED","SCOPE_LEVEL_AGENT","SCOPE_LEVEL_THREAD","SCOPE_LEVEL_USER"],"default":"SCOPE_LEVEL_UNSPECIFIED","description":"The scope level for a memory block's content storage.\n\n - SCOPE_LEVEL_UNSPECIFIED: Unspecified scope (defaults to AGENT).\n - SCOPE_LEVEL_AGENT: Agent-wide scope. Content is shared across all threads.\n - SCOPE_LEVEL_THREAD: Thread-local scope. Each thread has its own copy of the content.\n - SCOPE_LEVEL_USER: User-local scope. Each signed-in user has their own copy of the content,\nwhich follows them across all of their threads with the agent and is\ninvisible to other users. Only kinds whose allowed_scopes include it\n(or list no restriction) accept it."},"agentsV1ToolRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable tool identifier (hash of the original tool name).","readOnly":true},"name":{"type":"string","description":"The tool name (may be adapted name if adapters are applied).","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted.","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations).","readOnly":true}},"description":"Lightweight tool reference for context items.\nContains only metadata needed for context window visualization.\nIntentionally omits parameters_schema to keep responses lightweight."},"agentsV1ModelInfo":{"type":"object","properties":{"model_id":{"type":"string","description":"Model identifier (e.g., \"gpt-4o\", \"claude-3-opus\").","readOnly":true},"max_context_tokens":{"type":"integer","format":"int64","description":"Maximum context length in tokens.","readOnly":true},"max_output_tokens":{"type":"integer","format":"int64","description":"Maximum output tokens.","readOnly":true},"supports_vision":{"type":"boolean","description":"Whether the model supports vision/images.","readOnly":true},"supports_tools":{"type":"boolean","description":"Whether the model supports tool/function calling.","readOnly":true},"supports_structured_output":{"type":"boolean","description":"Whether the model supports structured output (JSON mode).","readOnly":true},"supports_streaming":{"type":"boolean","description":"Whether the model supports streaming responses.","readOnly":true},"supports_reasoning":{"type":"boolean","description":"Whether the model supports reasoning (chain-of-thought).","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"GPT-4o\", \"Claude Sonnet 4.5\").","readOnly":true},"family":{"type":"string","description":"Model family grouping (e.g., \"gpt-4o\", \"claude-4.5\", \"qwen2\").","readOnly":true},"license":{"type":"string","description":"License information (e.g., for open-weight models).","readOnly":true},"parameter_count":{"type":"string","format":"uint64","description":"Number of model parameters.","readOnly":true},"quantization":{"type":"string","description":"Quantization level (e.g., \"Q4_K_M\", \"Q8_0\").","readOnly":true},"supports_documents":{"type":"boolean","description":"Whether the model supports document inputs (PDFs, text files).","readOnly":true},"max_inline_artifact_bytes":{"type":"string","format":"uint64","description":"Maximum size of a single tool result that can be inlined into a\ngeneration request, in raw bytes. Already accounts for base64 expansion\nand a safety margin for request overhead.","readOnly":true},"deprecated":{"type":"boolean","description":"Whether the model is deprecated: still usable, but slated for retirement.","readOnly":true},"retired":{"type":"boolean","description":"Whether the model is retired: loadable (so existing threads/agents don't\nbreak) but generation is refused.","readOnly":true},"replacement_model":{"type":"string","description":"Recommended replacement model id when deprecated or retired.","readOnly":true},"pricing":{"$ref":"#/components/schemas/agentsV1ModelPricing"}},"description":"Information about a model and its capabilities."},"agentsV1ModelPricing":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1DatedRates"},"description":"Effective-dated rate rows. Windows should not overlap; if they do, the\nearliest-starting matching row wins so the outcome is deterministic.","readOnly":true}},"description":"Complete pricing knowledge for one model: its effective-dated rate rows.\n\nAn empty `rows` list is a valid \"priced at zero\" card for local models —\ndistinct from a model carrying no `ModelPricing` at all, which means its\ncost is unknown, not free."},"agentsV1DatedRates":{"type":"object","properties":{"effective_from":{"type":"string","format":"date-time","description":"Inclusive start of this row's validity. Absent = open-ended past.","readOnly":true},"effective_until":{"type":"string","format":"date-time","description":"Exclusive end of this row's validity. Absent = open-ended future.","readOnly":true},"base":{"$ref":"#/components/schemas/agentsV1RateCard"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1TierRates"},"description":"Long-context tiers: token-threshold bands above `base`, ascending by\n`threshold_tokens`. Empty = flat pricing. A request's total prompt size\nselects the highest tier whose threshold it reaches, or `base` below\nevery threshold.","readOnly":true}},"description":"One effective-dated pricing row: the rates in force during a validity\nwindow. A model whose price changes on a schedule carries several rows\ndiffering only in rates and effective bounds."},"agentsV1RateCard":{"type":"object","properties":{"input_per_mtok":{"type":"number","format":"double","description":"Fresh (uncached) input, USD per million tokens.","readOnly":true},"output_per_mtok":{"type":"number","format":"double","description":"Output, USD per million tokens. Includes reasoning/thinking tokens.","readOnly":true},"cache_read_per_mtok":{"type":"number","format":"double","description":"Tokens served from cache, USD per million tokens.","readOnly":true},"cache_write_per_mtok":{"type":"number","format":"double","description":"Cache writes at any TTL, USD per million tokens — for providers with a\nsingle write rate regardless of TTL.","readOnly":true},"cache_write_by_ttl":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWriteRate"},"description":"Per-TTL cache-write overrides, consulted before `cache_write_per_mtok`.","readOnly":true}},"description":"One complete set of USD-per-million-token rates. A missing cache rate is\nnot zero — it means the dimension is unpublished, and cost computation\nfalls back loudly (billed at the fresh-input rate, flagged estimated)."},"agentsV1CacheWriteRate":{"type":"object","properties":{"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds this rate applies to (e.g. 300 for a 5-minute bucket,\n3600 for a 1-hour bucket).","readOnly":true},"per_mtok":{"type":"number","format":"double","description":"USD per million tokens written into this bucket.","readOnly":true}},"description":"USD rate for cache writes at one specific TTL bucket."},"agentsV1TierRates":{"type":"object","properties":{"threshold_tokens":{"type":"integer","format":"int64","description":"Prompt-size threshold (total prompt tokens: fresh + cache read + cache\nwrite) at which these rates activate.","readOnly":true},"card":{"$ref":"#/components/schemas/agentsV1RateCard"}},"description":"One long-context tier band: requests whose total prompt tokens meet or\nexceed `threshold_tokens` (and fall below the next tier's threshold, when\none exists) bill the entire request — every class, input and output — at\n`card` instead of the base card."},"agentsV1ContextSummary":{"type":"object","properties":{"fixed_tokens":{"type":"integer","format":"int64","description":"Tokens used by fixed context (immutable memory + tools).","readOnly":true},"volatile_tokens":{"type":"integer","format":"int64","description":"Tokens used by volatile context (mutable memory).","readOnly":true},"compactable_tokens":{"type":"integer","format":"int64","description":"Tokens used by compactable context (conversation).","readOnly":true},"total_used_tokens":{"type":"integer","format":"int64","description":"Total tokens currently in use.","readOnly":true},"available_tokens":{"type":"integer","format":"int64","description":"Tokens available before hitting the context limit.","readOnly":true}},"description":"Summary of token usage by category."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/context":{"get":{"summary":"Get Thread Context (Astral2, run)","description":"Gets thread context information including all context items with token counts.\n\nReturns a unified view of all items contributing to the context window:\n- Memory blocks (fixed and volatile)\n- Enabled tools (fixed)\n- Conversation history (compactable)\n\nEach item includes its token count for context budget management.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `GetThreadContext` on `/agents/{agent_id}`.","operationId":"RunAstral2GetThreadContext","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetThreadContextResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"The thread ID.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events (Astral2, run)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Astral2, run)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"RunAstral2GetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message And Wait (Astral2, run)

> Sends a message and streams back response events synchronously.\
> \
> This RPC adds user input to the specified thread and returns a stream\
> of events representing the assistant's response. Events include output text,\
> tool calls, and completion metadata.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`SendMessageAndWait\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageSyncBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message and stream response events synchronously."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/events":{"post":{"summary":"Send Message And Wait (Astral2, run)","description":"Sends a message and streams back response events synchronously.\n\nThis RPC adds user input to the specified thread and returns a stream\nof events representing the assistant's response. Events include output text,\ntool calls, and completion metadata.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `SendMessageAndWait` on `/agents/{agent_id}`.","operationId":"RunAstral2SendMessageAndWait","responses":{"200":{"description":"A successful response.(streaming responses)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/agentsV1Event"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"Stream result of v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageSyncBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Set Thread Feedback (Astral2, run)

> Sets feedback (like/dislike) for a generation response.\
> \
> Feedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\
> Setting the same feedback that already exists is a no-op.\
> Use FEEDBACK\_TYPE\_UNSPECIFIED to clear existing feedback.\
> \
> Feedback is stored with the thread and is purely for analytics/UI purposes.\
> It is not visible to the LLM.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`SetThreadFeedback\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SetFeedbackResponse":{"type":"object","properties":{"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"previous_feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Response for setting feedback on a generation."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSetFeedbackBody":{"type":"object","properties":{"generation_id":{"type":"string","description":"Required. The generation ID (from GenerationComplete.id)."},"feedback_type":{"$ref":"#/components/schemas/agentsV1FeedbackType"}},"description":"Request to set feedback for a generation response."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/feedback":{"post":{"summary":"Set Thread Feedback (Astral2, run)","description":"Sets feedback (like/dislike) for a generation response.\n\nFeedback is mutually exclusive - setting LIKE removes any DISLIKE and vice versa.\nSetting the same feedback that already exists is a no-op.\nUse FEEDBACK_TYPE_UNSPECIFIED to clear existing feedback.\n\nFeedback is stored with the thread and is purely for analytics/UI purposes.\nIt is not visible to the LLM.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `SetThreadFeedback` on `/agents/{agent_id}`.","operationId":"RunAstral2SetThreadFeedback","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SetFeedbackResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread containing the generation.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSetFeedbackBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Message (Astral2, run)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/input":{"post":{"summary":"Send Message (Astral2, run)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"RunAstral2SendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Astral2, run)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Astral2, run)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"RunAstral2StreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## List Sub Agents (Astral2, run)

> Lists sub-agents configured for a thread.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`ListSubAgents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListSubAgentsResponse":{"type":"object","properties":{"sub_agents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1SubAgent"},"description":"The sub-agents configured for the thread."},"is_customized":{"type":"boolean","description":"Whether this represents a per-thread customization (vs inherited from agent)."}},"description":"Response message for ListSubAgents."},"agentsV1SubAgent":{"type":"object","properties":{"sub_agent_id":{"type":"string","description":"The unique sub-agent identifier (nanoid).","readOnly":true},"kind":{"type":"string","description":"The sub-agent caller kind (e.g., \"local\", \"a2a\").","readOnly":true},"config":{"type":"object","description":"Kind-specific configuration.","readOnly":true},"name":{"type":"string","description":"Display name shown to the LLM (e.g., \"Researcher\")."},"description":{"type":"string","description":"Description of what this sub-agent does (shown to the LLM)."},"variable_mappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Explicit variable mappings: sub-agent var name -> value (supports $parentVar syntax)."}},"description":"A configured sub-agent belonging to an agent."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/sub-agents":{"get":{"summary":"List Sub Agents (Astral2, run)","description":"Lists sub-agents configured for a thread.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `ListSubAgents` on `/agents/{agent_id}`.","operationId":"RunAstral2ListSubAgents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListSubAgentsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread whose sub-agents to list.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Tool Call (Astral2, run)

> Injects a deterministic tool call into a thread.\
> \
> Appends an assistant-voice preamble announcing the call as an externally\
> requested action, then a synthetic ToolCallStart (plus one\
> ToolCallArgument per supplied argument) to the thread event log under\
> the generation lock, executes the tool through the normal dispatcher,\
> and continues with an LLM turn that has the tool result in context. The\
> preamble keeps the model from misattributing the call to itself.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`SendToolCall\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolCallResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the call was accepted (validated and queued for execution)."},"tool_call_id":{"type":"string","description":"The minted tool_call_id. Clients can correlate against the resulting\nToolCallStart / ToolResult events on the thread event stream."}},"description":"Response from injecting a tool call."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolCallBody":{"type":"object","properties":{"tool_name":{"type":"string","description":"Required. Tool name as advertised by the agent's tool catalog."},"arguments":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"},"description":"Arguments to the tool, keyed by parameter name. Each Value carries the\ntyped argument exactly as a generator would have produced it."}},"description":"Request to inject a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (and one ToolCallArgument\nper supplied argument) to the thread event log under the generation lock,\nexecutes the tool through the normal dispatcher, and continues with an LLM\nturn that has the tool result in context. The preamble keeps the model\nfrom misattributing the call to itself."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/tool-calls":{"post":{"summary":"Send Tool Call (Astral2, run)","description":"Injects a deterministic tool call into a thread.\n\nAppends an assistant-voice preamble announcing the call as an externally\nrequested action, then a synthetic ToolCallStart (plus one\nToolCallArgument per supplied argument) to the thread event log under\nthe generation lock, executes the tool through the normal dispatcher,\nand continues with an LLM turn that has the tool result in context. The\npreamble keeps the model from misattributing the call to itself.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `SendToolCall` on `/agents/{agent_id}`.","operationId":"RunAstral2SendToolCall","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolCallResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to inject the call into.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolCallBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Send Tool Result (Astral2, run)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Astral2, run)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"RunAstral2SendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Upload Thread File (Astral2, run)

> Upload a file to a thread\
> \
> Accepts a \`multipart/form-data\` body with a single \`file\` part\
> and stores it for the thread under \`uploads\://\<filename>\`.\
> Returns the artifact URI plus the recorded MIME type, byte\
> size, and filename.\
> \
> The MIME type is taken from the part's \`Content-Type\` header when\
> the browser supplies one, falls back to a guess based on the\
> filename extension, and finally to \`application/octet-stream\`.\
> \
> Multipart parts other than \`file\` are accepted and ignored, leaving\
> room for forward-compatible additions (e.g. a content hash, a TTL\
> override) without breaking older servers.\
> \
> \*\*Client example (browser, with progress):\*\*\
> \`\`\`javascript\
> const form = new FormData();\
> form.append('file', file);\
> \
> const xhr = new XMLHttpRequest();\
> xhr.upload.onprogress = (e) => {\
> &#x20; if (e.lengthComputable) {\
> &#x20;   console.log(\`uploaded ${e.loaded} / ${e.total}\`);\
> &#x20; }\
> };\
> xhr.onload = () => {\
> &#x20; if (xhr.status === 200) {\
> &#x20;   const { uri } = JSON.parse(xhr.responseText);\
> &#x20;   // include \`uri\` in SendMessage.documents\
> &#x20; }\
> };\
> xhr.open('POST', \`/api/v1/agents/${agentId}/threads/${threadId}/uploads\`);\
> xhr.send(form);\
> \`\`\`\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`UploadThreadFile\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}/uploads":{"post":{"summary":"Upload Thread File (Astral2, run)","description":"Upload a file to a thread\n\nAccepts a `multipart/form-data` body with a single `file` part\nand stores it for the thread under `uploads://<filename>`.\nReturns the artifact URI plus the recorded MIME type, byte\nsize, and filename.\n\nThe MIME type is taken from the part's `Content-Type` header when\nthe browser supplies one, falls back to a guess based on the\nfilename extension, and finally to `application/octet-stream`.\n\nMultipart parts other than `file` are accepted and ignored, leaving\nroom for forward-compatible additions (e.g. a content hash, a TTL\noverride) without breaking older servers.\n\n**Client example (browser, with progress):**\n```javascript\nconst form = new FormData();\nform.append('file', file);\n\nconst xhr = new XMLHttpRequest();\nxhr.upload.onprogress = (e) => {\n  if (e.lengthComputable) {\n    console.log(`uploaded ${e.loaded} / ${e.total}`);\n  }\n};\nxhr.onload = () => {\n  if (xhr.status === 200) {\n    const { uri } = JSON.parse(xhr.responseText);\n    // include `uri` in SendMessage.documents\n  }\n};\nxhr.open('POST', `/api/v1/agents/${agentId}/threads/${threadId}/uploads`);\nxhr.send(form);\n```\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `UploadThreadFile` on `/agents/{agent_id}`.","operationId":"RunAstral2UploadThreadFile","responses":{"200":{"description":"Upload accepted; artifact written to uploads://&lt;filename&gt;.","content":{"application/json":{"schema":{"type":"object","required":["uri","mime_type","size","filename"],"properties":{"uri":{"type":"string","description":"Artifact URI to embed in SendMessage.documents."},"mime_type":{"type":"string","description":"MIME type recorded on the artifact."},"size":{"type":"integer","format":"int64","description":"Size of the stored content in bytes."},"filename":{"type":"string","description":"Filename the artifact is stored under within the uploads:// store."}}}}}},"400":{"description":"Multipart body missing the `file` part, missing a filename, or otherwise malformed."},"404":{"description":"Agent or thread not found."},"413":{"description":"Payload too large (server body-size limit exceeded)."},"500":{"description":"Internal store error."}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread the upload is staged into.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file payload. The part's filename and Content-Type are recorded on the artifact."}}}}}},"tags":["Agents"]}}}}
````

## Compact Thread (Astral2, run)

> Starts context compaction for a thread.\
> \
> Compaction summarizes conversation history to reduce context size while\
> preserving essential information. This RPC emits a CompactStart event\
> and returns the compact\_id for tracking.\
> \
> The actual compaction is performed asynchronously. Once complete, a\
> CompactComplete event with the summary content should be added to the\
> thread using the returned compact\_id.\
> \
> While compaction is in progress (CompactStart without CompactComplete),\
> the UI should block user input.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`CompactThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StartCompactionResponse":{"type":"object","properties":{"compact_id":{"type":"string","description":"The unique ID assigned to this compaction operation."}},"description":"Response for starting context compaction."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStartCompactionBody":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"Optional. The event ID from which to start compaction.\nEvents from this ID onwards (inclusive) will be compacted.\nIf not specified, the entire conversation is compacted."}},"description":"Request to start context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. A CompactStart event is emitted immediately,\nand an external compaction process should later emit CompactComplete with the\nsummary."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:compact":{"post":{"summary":"Compact Thread (Astral2, run)","description":"Starts context compaction for a thread.\n\nCompaction summarizes conversation history to reduce context size while\npreserving essential information. This RPC emits a CompactStart event\nand returns the compact_id for tracking.\n\nThe actual compaction is performed asynchronously. Once complete, a\nCompactComplete event with the summary content should be added to the\nthread using the returned compact_id.\n\nWhile compaction is in progress (CompactStart without CompactComplete),\nthe UI should block user input.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `CompactThread` on `/agents/{agent_id}`.","operationId":"RunAstral2CompactThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StartCompactionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to compact.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStartCompactionBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Fork Thread (Astral2, run)

> Forks (duplicates) a thread with all its data.\
> \
> Creates a new thread that is a complete copy of the source thread,\
> including events, feedback, memory customizations, scratchpad, plan,\
> and template config customizations.\
> Returns FAILED\_PRECONDITION if the source thread is currently generating.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`ForkThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceForkThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the new thread. Defaults to \"Fork of {source_title}\"."}},"description":"Request message for ForkThread (duplicate a thread with all its data)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:fork":{"post":{"summary":"Fork Thread (Astral2, run)","description":"Forks (duplicates) a thread with all its data.\n\nCreates a new thread that is a complete copy of the source thread,\nincluding events, feedback, memory customizations, scratchpad, plan,\nand template config customizations.\nReturns FAILED_PRECONDITION if the source thread is currently generating.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `ForkThread` on `/agents/{agent_id}`.","operationId":"RunAstral2ForkThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The source thread to fork.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceForkThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stop Thread (Astral2, run)

> Stops an in-progress generation in a thread.\
> \
> If a generation is currently running, it will be cancelled and a\
> GenerationFailed event with STOPPED kind will be emitted. If no\
> generation is in progress, this is a no-op and returns stopped=false.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`StopThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1StopResponse":{"type":"object","properties":{"stopped":{"type":"boolean","description":"True if a generation was active and has been stopped.\nFalse if no generation was in progress for the thread."}},"description":"Response for stopping an in-progress generation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceStopBody":{"type":"object","properties":{},"description":"Request to stop an in-progress generation in a thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:stop":{"post":{"summary":"Stop Thread (Astral2, run)","description":"Stops an in-progress generation in a thread.\n\nIf a generation is currently running, it will be cancelled and a\nGenerationFailed event with STOPPED kind will be emitted. If no\ngeneration is in progress, this is a no-op and returns stopped=false.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `StopThread` on `/agents/{agent_id}`.","operationId":"RunAstral2StopThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1StopResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread with the generation to stop.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceStopBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Wake Thread (Astral2, run)

> Wakes a thread that is currently sleeping (UI "Wake up" button).\
> \
> Atomically ends the pending sleep with \`interrupted\_by\_user = true\`,\
> cancels the scheduled wake task, and triggers a new generation so the\
> LLM observes the early return in its rebuilt history. No-op when no\
> sleep is pending; the call still triggers a normal Reminder-driven\
> resume in that case.\
> \
> Targets the built-in \`astral2\` agent in the run scope; the generic form is \`WakeThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1WakeResponse":{"type":"object","properties":{"woken":{"type":"boolean","description":"True if a pending sleep was found and ended early. False when the\nthread was not currently sleeping (the call still triggers a normal\nresume in that case, but no SleepCompleted is appended)."}},"description":"Response for waking a sleeping thread."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceWakeBody":{"type":"object","properties":{},"description":"Request to wake a thread that is currently sleeping.\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history.\n\nNo-op when the thread is not currently sleeping; this is a fall-through\nto a Reminder-triggered generation in that case."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/astral2/threads/{thread_id}:wake":{"post":{"summary":"Wake Thread (Astral2, run)","description":"Wakes a thread that is currently sleeping (UI \"Wake up\" button).\n\nAtomically ends the pending sleep with `interrupted_by_user = true`,\ncancels the scheduled wake task, and triggers a new generation so the\nLLM observes the early return in its rebuilt history. No-op when no\nsleep is pending; the call still triggers a normal Reminder-driven\nresume in that case.\n\nTargets the built-in `astral2` agent in the run scope; the generic form is `WakeThread` on `/agents/{agent_id}`.","operationId":"RunAstral2WakeThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1WakeResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the sleeping thread to wake.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceWakeBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Create Thread (Shifu, book version)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`shifu\` agent in the book version scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads":{"post":{"summary":"Create Thread (Shifu, book version)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `shifu` agent in the book version scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"BookShifuCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete Thread (Shifu, book version)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`shifu\` agent in the book version scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Shifu, book version)","description":"Deletes a thread and all its events.\n\nTargets the built-in `shifu` agent in the book version scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"BookShifuDeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Message (Shifu, book version)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`shifu\` agent in the book version scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads/{thread_id}/input":{"post":{"summary":"Send Message (Shifu, book version)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `shifu` agent in the book version scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"BookShifuSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Shifu, book version)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`shifu\` agent in the book version scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/agents/shifu/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Shifu, book version)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `shifu` agent in the book version scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"BookShifuStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## Create Thread (Shifu, book authentication)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`shifu\` agent in the book authentication scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads":{"post":{"summary":"Create Thread (Shifu, book authentication)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `shifu` agent in the book authentication scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"BookAuthenticationShifuCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"selected_authentication_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete Thread (Shifu, book authentication)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`shifu\` agent in the book authentication scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Shifu, book authentication)","description":"Deletes a thread and all its events.\n\nTargets the built-in `shifu` agent in the book authentication scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"BookAuthenticationShifuDeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"selected_authentication_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Send Message (Shifu, book authentication)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`shifu\` agent in the book authentication scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads/{thread_id}/input":{"post":{"summary":"Send Message (Shifu, book authentication)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `shifu` agent in the book authentication scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"BookAuthenticationShifuSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"selected_authentication_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Shifu, book authentication)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`shifu\` agent in the book authentication scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/authentications/{selected_authentication_id}/agents/shifu/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Shifu, book authentication)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `shifu` agent in the book authentication scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"BookAuthenticationShifuStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"selected_authentication_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## List Threads (Shifu, book connection)

> Lists all threads for an agent.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`ListThreads\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListThreadsResponse":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Thread"},"description":"The threads for the agent."}},"description":"Response message for ListThreads."},"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads":{"get":{"summary":"List Threads (Shifu, book connection)","description":"Lists all threads for an agent.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `ListThreads` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuListThreads","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListThreadsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional REL expression filtering over thread fields.\nEmpty = no filter.\n\nSupported fields:\n  agent_id                          (string)\n  status                            (string, snake_case discriminant)\n  variables.<key>, metadata.<key>   (string)\n  title, description                (optional string)\n  created_at, updated_at            (RFC-3339 string literal)\n  agent_version                     (integer)\n  origin.kind                       (string: \"schedule\" / \"sub_agent\")\n  origin.schedule.schedule_id       (string)\n  origin.sub_agent.parent_agent_id  (string)\n  origin.sub_agent.parent_thread_id (string)\n  origin.sub_agent.task_id          (string)\n  hydration                         (string: \"hydrated\" / \"dehydrated\")\n\nExamples:\n  variables.region == \"us-east\" && updated_at >= \"2026-05-01T00:00:00Z\"\n  title.contains(\"invoice\")\n  agent_version in [3, 4, 5]\n  origin.kind == \"schedule\"\n  has(origin.sub_agent.parent_agent_id)","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Create Thread (Shifu, book connection)

> Creates a new thread.\
> \
> The thread\_id is auto-generated. Optionally provide a title and description.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`CreateThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1Thread":{"type":"object","properties":{"thread_id":{"type":"string","description":"The unique thread identifier (auto-generated)."},"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"created_at":{"type":"string","format":"date-time","description":"When the thread was created."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Thread variables for configuration resolution.\nVariables are set at creation time and are immutable."},"feedback":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1FeedbackType"},"description":"User feedback for generation responses (keyed by generation_id).\nUsed for analytics and UI, not visible to the LLM."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary key-value metadata attached by the thread creator."},"event_count":{"type":"string","format":"int64","description":"Number of events in this thread."},"agent_version":{"type":"string","format":"uint64","description":"Agent version this thread is pinned to.\n\nThe thread resolves its agent template against this specific\nversion for the rest of its life. Moving a thread to a newer\nversion is an explicit user action (UpgradeThread / Deploy\nre-pin), never a side effect of an agent save.\n\nZero is the sentinel for threads created without a pin (e.g.\nbefore the agent_version column existed); the server resolves\nsuch threads as current head."},"updated_at":{"type":"string","format":"date-time","description":"When the thread was last modified.\n\nBumped on any state change: event append, metadata edit, feedback\nedit, variable extension via UpgradeThread, plan/memory/scratchpad\nwrites, etc. ListThreads returns threads sorted by this field in\ndescending order (most recently active first); pre-existing\nthreads from before this field was added fall back to created_at."},"created_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"updated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"origin":{"$ref":"#/components/schemas/agentsV1ThreadOrigin"},"status":{"$ref":"#/components/schemas/agentsV1ThreadStatus"},"status_updated_at":{"type":"string","format":"date-time","description":"When the thread entered its current status."},"plan_active":{"type":"boolean","description":"Whether a plan is active on the thread (orthogonal to status)."},"agent_id":{"type":"string","description":"The owning agent's id. Populated by cross-agent listings (ListAllThreads);\nempty for single-agent listings where the agent is implied by the request."},"agent_name":{"type":"string","description":"The owning agent's display name. Populated by cross-agent listings;\nempty otherwise."},"cost":{"$ref":"#/components/schemas/agentsV1Cost"},"stats":{"$ref":"#/components/schemas/agentsV1ThreadStats"},"dehydration":{"$ref":"#/components/schemas/agentsV1DehydrationState"}},"description":"A conversation thread with an AI agent."},"agentsV1FeedbackType":{"type":"string","enum":["FEEDBACK_TYPE_UNSPECIFIED","FEEDBACK_TYPE_LIKE","FEEDBACK_TYPE_DISLIKE"],"default":"FEEDBACK_TYPE_UNSPECIFIED","description":"Feedback type for a generation response.\n\n - FEEDBACK_TYPE_UNSPECIFIED: No feedback has been provided.\n - FEEDBACK_TYPE_LIKE: User liked the response.\n - FEEDBACK_TYPE_DISLIKE: User disliked the response."},"agentsV1PrincipalRef":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier. For OIDC this is the `sub` claim. For\ntrusted-header mode this is the header configured as `user_id`.\nFor `Fixed` mode it is the configured principal's id."},"kind":{"$ref":"#/components/schemas/agentsV1PrincipalKind"},"email":{"type":"string","description":"Email address if known. Optional because some IdPs don't expose\none (service accounts, machine identities)."},"display_name":{"type":"string","description":"Human-readable display name (`name` claim,\n`X-Forwarded-Preferred-Username`, configured display name in\nFixed mode)."},"component":{"type":"string","description":"For `PRINCIPAL_KIND_SYSTEM`, the in-process component that owns\nthis attribution (`\"backfill\"`, `\"bootstrap\"`, etc.)."}},"description":"Persistence-shape subset of a Principal stamped on stored entities\nas `created_by` / `updated_by`.\n\nThe full Principal (with raw claims and groups) only lives in\nmemory for the duration of a request; `PrincipalRef` is what gets\npersisted on agents, threads, and scheduled-task payloads."},"agentsV1PrincipalKind":{"type":"string","enum":["PRINCIPAL_KIND_UNSPECIFIED","PRINCIPAL_KIND_USER","PRINCIPAL_KIND_SERVICE","PRINCIPAL_KIND_SYSTEM"],"default":"PRINCIPAL_KIND_UNSPECIFIED","description":"Categorises a Principal by its origin.\n\nUsed in audit attribution to distinguish a real end user from a\nmachine-to-machine caller, and from internal components that\nmutate state without any user on whose behalf they are acting.\n\n - PRINCIPAL_KIND_USER: Authenticated end user.\n - PRINCIPAL_KIND_SERVICE: Non-human caller (machine-to-machine token, CI job).\n - PRINCIPAL_KIND_SYSTEM: Internal component (scheduler orphan sweep, backfill, etc.)."},"agentsV1ThreadOrigin":{"type":"object","properties":{"kind":{"type":"string","description":"Stable discriminator equal to the set `detail` arm's name\n(\"schedule\", \"sub_agent\", ...). Lets generic clients and filters\nswitch on the kind without knowing every variant."},"schedule":{"$ref":"#/components/schemas/agentsV1ScheduleOrigin"},"sub_agent":{"$ref":"#/components/schemas/agentsV1SubAgentOrigin"}},"description":"Why a thread was created. Absent on a thread means it was started\ndirectly (the normal interactive flow). New kinds are added as\nadditional `detail` arms without breaking existing ones."},"agentsV1ScheduleOrigin":{"type":"object","properties":{"schedule_id":{"type":"string","title":"The schedule whose occurrence created this thread. (The owning agent\nis implied by the thread.)"},"occurrence_at":{"type":"string","format":"date-time","description":"The scheduled fire time this thread corresponds to."}},"description":"A thread created because a schedule occurrence fired."},"agentsV1SubAgentOrigin":{"type":"object","properties":{"parent_agent_id":{"type":"string","description":"The agent that issued the delegation (the caller). The sub-thread\nlives under a different agent, so the parent agent id is qualified."},"parent_thread_id":{"type":"string","description":"The caller's thread that issued the delegation."},"task_id":{"type":"string","description":"The delegation task/call id the sub-thread id was derived from."}},"description":"A thread created because a parent agent delegated to a sub-agent."},"agentsV1ThreadStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/agentsV1ThreadStatusState"},"tool_label":{"type":"string","description":"ExecutingTool: the tool's rendered in-flight label."},"remote_count":{"type":"integer","format":"int64","description":"AwaitingTool: the number of open remote calls (>= 1)."},"wake_at":{"type":"string","format":"date-time","description":"Sleeping: the scheduled wake instant."},"sleep_reason":{"type":"string","description":"Sleeping: optional reason copied from the sleep request."},"retry_attempt":{"type":"integer","format":"int64","description":"Retrying: 1-indexed attempt number."},"retry_max_attempts":{"type":"integer","format":"int64","description":"Retrying: total attempts permitted."},"next_attempt_at":{"type":"string","format":"date-time","description":"Retrying: when the next attempt is scheduled, if known."},"error_kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"error_message":{"type":"string","description":"Failed: human-readable error message."}},"description":"What a thread is doing right now. A point-in-time field that changes many\ntimes within a single turn; a pure function of the thread's event history."},"agentsV1ThreadStatusState":{"type":"string","enum":["THREAD_STATUS_STATE_UNSPECIFIED","THREAD_STATUS_STATE_IDLE","THREAD_STATUS_STATE_THINKING","THREAD_STATUS_STATE_RESPONDING","THREAD_STATUS_STATE_EXECUTING_TOOL","THREAD_STATUS_STATE_DELEGATING","THREAD_STATUS_STATE_COMPACTING","THREAD_STATUS_STATE_TRANSFERRING","THREAD_STATUS_STATE_AWAITING_ANSWER","THREAD_STATUS_STATE_AWAITING_APPROVAL","THREAD_STATUS_STATE_AWAITING_TOOL","THREAD_STATUS_STATE_SLEEPING","THREAD_STATUS_STATE_DELEGATE_BLOCKED","THREAD_STATUS_STATE_RETRYING","THREAD_STATUS_STATE_FAILED","THREAD_STATUS_STATE_STOPPED"],"default":"THREAD_STATUS_STATE_UNSPECIFIED","description":"The set of thread status discriminants."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Cost":{"type":"object","properties":{"input_nano_usd":{"type":"string","format":"uint64","description":"Fresh-input tokens priced at the input rate."},"cache_read_nano_usd":{"type":"string","format":"uint64","description":"Cache reads priced at the cache-read rate."},"cache_write_nano_usd":{"type":"string","format":"uint64","description":"Cache writes priced at their per-TTL rates."},"output_nano_usd":{"type":"string","format":"uint64","description":"Output tokens priced at the output rate."},"total_nano_usd":{"type":"string","format":"uint64","description":"Sum of the four classes."},"estimated":{"type":"boolean","description":"Some component was priced through a loud fallback (missing cache\nrate, unknown cache-write TTL, legacy usage semantics, or an\nambiguous rate-card lookup) — the figure is an estimate, not exact."}},"description":"A computed USD cost in integer nano-USD, per billing class.\n\nNever persisted — always computed on request from the effective-dated\nrate card, so rate corrections apply retroactively while the underlying\ntoken accounting stays immutable."},"agentsV1ThreadStats":{"type":"object","properties":{"model":{"type":"string","description":"The latest model the thread generated on (e.g. \"claude-opus-4-8\").\nAbsent when the thread has never generated.","readOnly":true},"provider":{"type":"string","description":"Generator kind of the latest model (e.g. \"anthropic\"), used to resolve\nthe model badge glyph. Absent when the thread has never generated.","readOnly":true},"total_tokens":{"type":"string","format":"uint64","description":"Total tokens across every billing class of the thread's usage.","readOnly":true},"tool_calls":{"type":"string","format":"uint64","description":"Tool calls the thread has issued.","readOnly":true},"errors":{"type":"string","format":"uint64","description":"Thread-level failures: terminal generation failures and plan executions\nthat did not complete.","readOnly":true},"recent_activity":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Recent per-generation total token counts, oldest first, bounded to the\nmost recent generations. Rendered as the activity sparkline.","readOnly":true}},"description":"Display aggregates for a thread, projected from its usage aggregate at\nlisting time. Drives the monitoring-style thread card: the model badge,\nthe tool/error/token strip, and the activity sparkline."},"agentsV1DehydrationState":{"type":"object","properties":{"dehydrated_at":{"type":"string","format":"date-time","description":"When the thread was dehydrated."},"dehydrated_by":{"$ref":"#/components/schemas/agentsV1PrincipalRef"},"size_bytes":{"type":"string","format":"uint64","description":"Size of the archive in bytes."}},"description":"Operational dehydration lifecycle state for a thread. Present iff the thread\nhas been dehydrated (its data archived, leaving a tombstone). The archive's\nstorage internals are server-side only; clients see just when and by whom the\nthread was dehydrated and how large the archive is."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceCreateThreadBody":{"type":"object","properties":{"title":{"type":"string","description":"Optional human-readable title for the thread."},"description":{"type":"string","description":"Optional description of the thread's purpose or context."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables for thread-scoped configuration resolution.\nThese values fill the variables defined in the agent's configuration."}},"description":"Request to create a new thread."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads":{"post":{"summary":"Create Thread (Shifu, book connection)","description":"Creates a new thread.\n\nThe thread_id is auto-generated. Optionally provide a title and description.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `CreateThread` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuCreateThread","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1Thread"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceCreateThreadBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Delete Thread (Shifu, book connection)

> Deletes a thread and all its events.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`DeleteThread\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}":{"delete":{"summary":"Delete Thread (Shifu, book connection)","description":"Deletes a thread and all its events.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `DeleteThread` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuDeleteThread","responses":{"204":{"description":"No content."},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to delete.","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Get Thread Events (Shifu, book connection)

> Retrieves all events from a thread.\
> \
> This RPC returns the complete history of events for a thread, including\
> user inputs, assistant responses, tool calls, and their results.\
> Events are returned in chronological order.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`GetThreadEvents\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1GetEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events in the thread, ordered chronologically."}},"description":"Response message for GetEvents."},"agentsV1Event":{"type":"object","properties":{"id":{"type":"string","format":"uint64","description":"Sequence ID within the thread (0-indexed).\nUsed for SSE Last-Event-ID reconnection support.\nOnly present when events are retrieved from a thread context."},"task_id":{"type":"string","description":"Scopes this event to a sub-agent task.\nNot set for parent (top-level) scope events."},"recorded_at_ms":{"type":"string","format":"int64","description":"Wall-clock time the event was recorded (appended to the store), in\nmilliseconds since the Unix epoch. Present for persisted events; absent\nfor ephemeral (id-less) notifications. Consumers derive a thread's\nstatus-change time from this recorded time."},"deleted":{"type":"boolean","description":"Whether this event belongs to a deleted turn.\nOnly set when include_deleted is true in the request."},"instruction_text":{"$ref":"#/components/schemas/agentsV1InstructionText"},"input_text":{"$ref":"#/components/schemas/agentsV1InputText"},"input_image":{"$ref":"#/components/schemas/agentsV1InputImage"},"output_text":{"$ref":"#/components/schemas/agentsV1OutputText"},"tool_call_start":{"$ref":"#/components/schemas/agentsV1ToolCallStart"},"tool_call_argument":{"$ref":"#/components/schemas/agentsV1ToolCallArgument"},"tool_result":{"$ref":"#/components/schemas/agentsV1ToolResult"},"generation_complete":{"$ref":"#/components/schemas/agentsV1GenerationComplete"},"reasoning_text":{"$ref":"#/components/schemas/agentsV1ReasoningText"},"reasoning_summary":{"$ref":"#/components/schemas/agentsV1ReasoningSummary"},"generation_failed":{"$ref":"#/components/schemas/agentsV1GenerationFailed"},"interrupt":{"$ref":"#/components/schemas/agentsV1Interrupt"},"interrupt_answer":{"$ref":"#/components/schemas/agentsV1InterruptAnswer"},"compact_start":{"$ref":"#/components/schemas/agentsV1CompactStart"},"compact_complete":{"$ref":"#/components/schemas/agentsV1CompactComplete"},"compact_failed":{"$ref":"#/components/schemas/agentsV1CompactFailed"},"reminder":{"$ref":"#/components/schemas/agentsV1Reminder"},"input_document":{"$ref":"#/components/schemas/agentsV1InputDocument"},"task_requested":{"$ref":"#/components/schemas/agentsV1TaskRequested"},"task_completed":{"$ref":"#/components/schemas/agentsV1TaskCompleted"},"task_failed":{"$ref":"#/components/schemas/agentsV1TaskFailed"},"follow_up":{"$ref":"#/components/schemas/agentsV1FollowUp"},"tool_approval_requested":{"$ref":"#/components/schemas/agentsV1ToolApprovalRequested"},"tool_approval_granted":{"$ref":"#/components/schemas/agentsV1ToolApprovalGranted"},"tool_approval_denied":{"$ref":"#/components/schemas/agentsV1ToolApprovalDenied"},"sleep_requested":{"$ref":"#/components/schemas/agentsV1SleepRequested"},"sleep_completed":{"$ref":"#/components/schemas/agentsV1SleepCompleted"},"transfer_requested":{"$ref":"#/components/schemas/agentsV1TransferRequested"},"transfer_completed":{"$ref":"#/components/schemas/agentsV1TransferCompleted"},"transfer_failed":{"$ref":"#/components/schemas/agentsV1TransferFailed"},"task_started":{"$ref":"#/components/schemas/agentsV1TaskStarted"},"task_suspended":{"$ref":"#/components/schemas/agentsV1TaskSuspended"},"task_resumed":{"$ref":"#/components/schemas/agentsV1TaskResumed"},"sleep_failed":{"$ref":"#/components/schemas/agentsV1SleepFailed"},"events_deleted":{"$ref":"#/components/schemas/agentsV1EventsDeleted"},"event_enqueued":{"$ref":"#/components/schemas/agentsV1EventEnqueued"},"event_popped":{"$ref":"#/components/schemas/agentsV1EventPopped"},"input_artifact":{"$ref":"#/components/schemas/agentsV1InputArtifact"}},"description":"An event in a generation sequence.\n\nEvents represent all occurrences during generation, both from input\n(instructions, prompts, tool results) and output (generated text,\ntool calls, generation metadata)."},"agentsV1InstructionText":{"type":"object","properties":{"text":{"type":"string","description":"The instruction text."},"mutable":{"type":"boolean","description":"Whether the text is expected to change between turns (e.g. a writable\nmemory block). Generators that support prompt caching use this to keep\nvolatile content outside the cached prefix."},"id":{"type":"string","description":"Stable identifier when the instruction comes from a named source\n(e.g. a memory block id). Unset for freeform instructions."}},"description":"Instruction text providing context or directives.\nTypically appears at the beginning to set generator behavior."},"agentsV1InputText":{"type":"object","properties":{"text":{"type":"string","description":"The input text."}},"description":"Input text prompting the generator."},"agentsV1InputImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"Input image for vision models."},"agentsV1OutputText":{"type":"object","properties":{"text":{"type":"string","description":"The generated output text."}},"description":"Output text generated by the model."},"agentsV1ToolCallStart":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of this tool call (for parallel tool calls)."},"id":{"type":"string","description":"Unique identifier for this tool call."},"name":{"type":"string","description":"Name of the tool being called."},"is_remote":{"type":"boolean","description":"Whether this tool requires remote execution.\nRemote tools pause generation and wait for an external system\nto execute them and post the result back via API."},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\"."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from function call parts."}},"description":"Tool call initiated by the generator."},"agentsV1ToolCallArgument":{"type":"object","properties":{"index":{"type":"integer","format":"int32","description":"Index of the tool call this belongs to."},"name":{"type":"string","description":"Argument name (the JSON key)."},"value":{"$ref":"#/components/schemas/agentsV1Value"}},"description":"A single named argument for a tool call.\nEach event carries one complete argument (name + typed value).\nGenerators emit one event per argument as each top-level key-value\npair is parsed from the streaming JSON."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."},"agentsV1ToolResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"ID of the tool call this is responding to."},"name":{"type":"string","description":"Name of the tool that was called."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional)."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Result from executing a tool."},"agentsV1GenerationComplete":{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model that was used for generation."},"id":{"type":"string","description":"Unique response identifier."},"agent_version":{"type":"string","format":"uint64","description":"Agent version active when this generation ran. Absent for events written\nbefore this field existed (the rating update falls back to the thread's\npinned version for those)."},"provider":{"type":"string","description":"Generator kind that produced this completion (e.g. \"anthropic\",\n\"bedrock\"), stamped by the agent loop so rate-card lookup is exact.\nAbsent for events written before this field existed."}},"description":"Generation completed successfully.\nThis is always the final event in both streaming and non-streaming modes."},"agentsV1Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the prompt."},"completion_tokens":{"type":"integer","format":"int32","description":"Number of tokens in the completion."},"total_tokens":{"type":"integer","format":"int32","description":"Total number of tokens used (prompt + completion)."},"cache":{"$ref":"#/components/schemas/agentsV1CacheUsage"}},"description":"Token usage statistics for a generation request."},"agentsV1CacheUsage":{"type":"object","properties":{"read_tokens":{"type":"integer","format":"int64","description":"Tokens served from cache on this request."},"write_tokens":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1CacheWrite"},"description":"Tokens written to cache on this request, bucketed by TTL.\nEmpty for providers without explicit write accounting."}},"description":"Prompt cache usage on a single generation request."},"agentsV1CacheWrite":{"type":"object","properties":{"tokens":{"type":"integer","format":"int64","description":"Number of tokens written into this bucket."},"ttl_seconds":{"type":"integer","format":"int64","description":"TTL in seconds for the written bucket (provider-specific interpretation)."}},"description":"A single cache-write bucket — tokens written at a given TTL."},"agentsV1ReasoningText":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning text content."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nAnthropic: the signature field from thinking blocks.\nOpenAI: the encrypted_content from reasoning items."},"progress_update":{"type":"boolean","description":"True when this block is a progress update rather than reasoning: a short\nnote the model writes for the user between tool calls. Clients show it as\nnarration; it replays like any other thinking block."}},"description":"Reasoning text from the model's chain of thought.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1ReasoningSummary":{"type":"object","properties":{"text":{"type":"string","description":"The reasoning summary text."}},"description":"Summary of the model's reasoning process.\nOnly available with OpenAI Responses API for reasoning models."},"agentsV1GenerationFailed":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"retryable":{"type":"boolean","description":"When `true`, the agent loop is automatically retrying this generation;\nthe next attempt fires at `next_attempt_at`. When `false`, this is a\nterminal failure (either non-retryable by classification, or the\nretry budget is exhausted)."},"attempt":{"type":"integer","format":"int64","description":"1-indexed attempt number that this failure corresponds to. Zero when\n`retryable` is false and the field is unused."},"max_attempts":{"type":"integer","format":"int64","description":"Total attempts permitted in this retry budget. Zero when `retryable`\nis false and the field is unused."},"next_attempt_at":{"type":"string","format":"date-time","description":"Wall-clock instant at which the next attempt is scheduled. Absent\nwhen `retryable` is false."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the failed attempt ran on, when known."},"provider":{"type":"string","description":"Generator kind of the failed attempt, when known."}},"description":"Generation failed with an error.\nThe error message should be displayed to the user."},"agentsV1GenerationErrorKind":{"type":"string","enum":["GENERATION_ERROR_KIND_UNSPECIFIED","GENERATION_ERROR_KIND_CONTEXT_TOO_LONG","GENERATION_ERROR_KIND_PROVIDER_ERROR","GENERATION_ERROR_KIND_API_ERROR","GENERATION_ERROR_KIND_CONTENT_FILTERED","GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_INVALID_REQUEST","GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED","GENERATION_ERROR_KIND_SERIALIZATION_ERROR","GENERATION_ERROR_KIND_STREAM_ERROR","GENERATION_ERROR_KIND_CONFIGURATION_ERROR","GENERATION_ERROR_KIND_INTERNAL_ERROR","GENERATION_ERROR_KIND_STOPPED","GENERATION_ERROR_KIND_SHUTDOWN","GENERATION_ERROR_KIND_AUTHENTICATION","GENERATION_ERROR_KIND_OVERLOADED","GENERATION_ERROR_KIND_STREAM_DROPPED","GENERATION_ERROR_KIND_LOST","GENERATION_ERROR_KIND_REQUEST_TOO_LARGE"],"default":"GENERATION_ERROR_KIND_UNSPECIFIED","description":"Error kind for generation failures.\n\n - GENERATION_ERROR_KIND_UNSPECIFIED: Unspecified error kind.\n - GENERATION_ERROR_KIND_CONTEXT_TOO_LONG: Input context exceeds the model's maximum token limit.\n - GENERATION_ERROR_KIND_PROVIDER_ERROR: Upstream provider returned an error.\n - GENERATION_ERROR_KIND_API_ERROR: API-level error from the provider.\n - GENERATION_ERROR_KIND_CONTENT_FILTERED: Response was filtered by content safety policies.\n - GENERATION_ERROR_KIND_LENGTH_LIMIT_EXCEEDED: Output exceeded the maximum length limit.\n - GENERATION_ERROR_KIND_INVALID_REQUEST: Request was malformed or invalid.\n - GENERATION_ERROR_KIND_RATE_LIMIT_EXCEEDED: Rate limit was exceeded.\n - GENERATION_ERROR_KIND_SERIALIZATION_ERROR: Failed to serialize or deserialize data.\n - GENERATION_ERROR_KIND_STREAM_ERROR: Error occurred during response streaming.\n - GENERATION_ERROR_KIND_CONFIGURATION_ERROR: Generator configuration is invalid.\n - GENERATION_ERROR_KIND_INTERNAL_ERROR: Internal server error.\n - GENERATION_ERROR_KIND_STOPPED: Generation was stopped by the user or system.\n - GENERATION_ERROR_KIND_SHUTDOWN: Server is shutting down.\n - GENERATION_ERROR_KIND_AUTHENTICATION: Authentication failed (invalid/missing credentials).\n - GENERATION_ERROR_KIND_OVERLOADED: Provider is overloaded / temporarily unavailable.\n - GENERATION_ERROR_KIND_STREAM_DROPPED: Stream ended mid-response without a terminal event (mid-stream drop).\nDistinct from STREAM_ERROR (transient transport blips that may\nsucceed on retry): once partial tokens have been delivered to the\nuser, retrying produces a different response that won't align with\nwhat's already shown. Non-retryable by classification.\n - GENERATION_ERROR_KIND_LOST: The server lost this generation: the process running it died\nmid-turn, and the failure was synthesized afterwards to close out\nthe dangling thread tail. Distinct from STOPPED (a user action)\nand from provider errors — nothing was wrong with the request.\n - GENERATION_ERROR_KIND_REQUEST_TOO_LARGE: The request payload exceeded the platform's request-size limit (e.g.\nBedrock's 20 MB / direct API 32 MB cap), distinct from CONTEXT_TOO_LONG\n(a token-window overflow). Recoverable by offloading large tool results\nout of context and retrying."},"agentsV1Interrupt":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"Unique identifier for this interrupt (for correlating reply)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions to ask the user."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay.\nGemini: the thoughtSignature from the ask_user function call."}},"description":"Generation paused - LLM is asking the user question(s).\nThis is a terminal event (like GenerationComplete) - no more events follow\nuntil the user responds."},"agentsV1InterruptQuestion":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this question."},"question":{"type":"string","description":"The full question text."},"header":{"type":"string","description":"Short label displayed as chip/tag (max 12 chars)."},"options":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptOption"},"description":"Available choices (2-4 options)."},"multi_select":{"type":"boolean","description":"If true, user can select multiple options."}},"description":"A single question in an interrupt."},"agentsV1InterruptOption":{"type":"object","properties":{"label":{"type":"string","description":"Display text for this option (1-5 words)."},"description":{"type":"string","description":"Explanation of what this option means."}},"description":"A question option for the user to select."},"agentsV1InterruptAnswer":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id being answered."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions. Empty if user redirected."}},"description":"User's answer to interrupt questions (stored as event).\nEmpty answers list indicates user redirected with a different message."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1CompactStart":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking start and complete events."},"from_event_id":{"type":"string","format":"uint64","description":"Event ID of the first GenerationComplete or CompactComplete to include.\nEverything from this event to now gets compacted.\nIf not set, compact entire conversation."}},"description":"Marks the start of a compaction operation.\nBlocks user input until CompactComplete is received."},"agentsV1CompactComplete":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"content":{"type":"string","description":"The compacted content sent to LLM as context."},"usage":{"$ref":"#/components/schemas/agentsV1Usage"},"model":{"type":"string","description":"Model the compaction generation ran on, when known."},"provider":{"type":"string","description":"Generator kind of the compaction generation, when known."}},"description":"Completes a compaction operation with the compacted content.\nEvents in the compacted range are replaced by this content\nwhen building the LLM context."},"agentsV1CompactFailed":{"type":"object","properties":{"compact_id":{"type":"string","description":"Unique identifier linking to CompactStart."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Marks the failure of a compaction operation."},"agentsV1Reminder":{"type":"object","properties":{"text":{"type":"string","description":"The reminder text."}},"description":"System-injected reminder for LLM context.\nUsed for plan nudges and completion summaries. The raw text is stored\nwithout XML tags; each generator wraps it in <system-reminder> tags\nduring conversion."},"agentsV1InputDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"Input document (text files, PDFs, code files)."},"agentsV1TaskRequested":{"type":"object","properties":{"call_id":{"type":"string","title":"The invoke_agent_* tool-call id. The recording-stable handle the LLM uses\nto address the task on resume. (No task_id yet — the sub-thread does not\nexist until TaskStarted.)"},"sub_agent_id":{"type":"string","description":"The configured sub-agent ID to invoke."},"input":{"type":"string","description":"The message/input to send to the sub-agent."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Artifact URIs to hand to the sub-agent, materialized into its uploads."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-invocation values for the target agent's exposed variables."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."}},"description":"Sub-agent invocation requested by the LLM."},"agentsV1TaskCompleted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"result":{"type":"string","description":"Collected output text from the sub-agent."},"call_id":{"type":"string","description":"The tool call this completion resolves (invoke or the last resume)."}},"description":"Sub-agent invocation completed."},"agentsV1TaskFailed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id (task identity)."},"message":{"type":"string","description":"Error message."},"kind":{"$ref":"#/components/schemas/agentsV1GenerationErrorKind"},"call_id":{"type":"string","description":"The tool call this failure resolves (invoke or the last resume)."}},"description":"Sub-agent invocation failed."},"agentsV1FollowUp":{"type":"object","properties":{"suggestion":{"type":"string","description":"The suggested follow-up message text."}},"description":"A streamed follow-up suggestion chip.\nEphemeral: not persisted, only streamed to SSE clients."},"agentsV1ToolApprovalRequested":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolCallStart event."}},"description":"Approval requested for a pending tool call.\nEmitted when a tool's requires_approval flag is true after the model\nemits the corresponding ToolCallStart. The agent loop pauses (turn\nreturns interrupted) until a matching ToolApprovalGranted or\nToolApprovalDenied event is appended to the thread."},"agentsV1ToolApprovalGranted":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."}},"description":"User granted approval for a pending tool call.\nResume scan dispatches the tool when this event is present without a\nmatching ToolResult."},"agentsV1ToolApprovalDenied":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the corresponding ToolApprovalRequested event."},"reason":{"type":"string","description":"Optional reason supplied by the user when denying."}},"description":"User denied approval for a pending tool call.\nResume scan synthesizes a ToolResult with success=false and the\nreason in the error field when this event is present without a\nmatching ToolResult."},"agentsV1SleepRequested":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Correlation handle. Equal to the ScheduledTaskId registered with\nthe scheduler, and equal to sleep_id echoed in the matching\nSleepCompleted."},"requested_at":{"type":"string","format":"int64","description":"Wall-clock time the request was emitted (Unix seconds)."},"wake_at":{"type":"string","format":"int64","description":"Wall-clock time the wake is scheduled for (Unix seconds)."},"seconds":{"type":"integer","format":"int64","description":"Requested duration in seconds (post-clamp to the operator cap)."},"reason":{"type":"string","description":"Optional reason, copied through from the tool call arguments."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque data required for multi-turn replay."}},"description":"Generation paused — LLM called the synthetic `sleep` tool.\nTerminal event, like Interrupt. The agent runner schedules the wake\nand exits; resumption happens via SleepCompleted appended by the\nAgentWakeHandler (or by the message-receive path on user interrupt)."},"agentsV1SleepCompleted":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"slept_for_seconds":{"type":"string","format":"uint64","description":"How long we actually slept, in seconds."},"woke_at":{"type":"string","format":"int64","description":"Wall-clock time we woke (Unix seconds)."},"interrupted_by_user":{"type":"boolean","description":"True when the sleep was cut short by a user message arriving while\nthe thread was sleeping; false when the scheduled wake fired\nnaturally."}},"description":"Sleep ended and the thread is being resumed."},"agentsV1TransferRequested":{"type":"object","properties":{"to":{"type":"string","description":"The agent to receive control (a referenced local agent id, or \"main\")."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"},"transfer_id":{"type":"string","description":"Unique transfer id; the originating tool call's id for agent-initiated\ntransfers, loop-generated for operator-forced ones."},"message":{"type":"string","description":"Optional handoff note to the target (the transfer tool's message argument)."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob for faithful replay (e.g. Gemini thought_signature)."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"LLM-supplied values for the target profile's exposed (unmapped, non-fixed)\nvariables, captured from the transfer tool call. Empty for operator-forced\ntransfers and transfer_back."}},"description":"The LLM or an operator requested handing the conversation to another agent on\nthe same thread. The loop enacts it and appends TransferCompleted (or\nTransferFailed)."},"agentsV1TransferInitiator":{"type":"string","enum":["TRANSFER_INITIATOR_UNSPECIFIED","TRANSFER_INITIATOR_AGENT","TRANSFER_INITIATOR_USER"],"default":"TRANSFER_INITIATOR_UNSPECIFIED","description":"Who initiated a transfer."},"agentsV1TransferCompleted":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"to":{"type":"string","description":"The agent that received control."},"initiated_by":{"$ref":"#/components/schemas/agentsV1TransferInitiator"}},"description":"A requested transfer was enacted; the target agent is now active. The active\nagent and the derived transfer stack are recomputed by folding these over the\nlog; there is no `from` (it is always the prior top)."},"agentsV1TransferFailed":{"type":"object","properties":{"transfer_id":{"type":"string","description":"The transfer_id of the matching TransferRequested."},"reason":{"type":"string","description":"Why the transfer was rejected."}},"description":"A requested transfer was rejected (depth guard, unknown target)."},"agentsV1TaskStarted":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id — the stable task identity."},"call_id":{"type":"string","description":"The invoke_agent_* call this task was born from."}},"description":"The delegate's sub-thread was created and its run began."},"agentsV1TaskSuspended":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id."},"call_id":{"type":"string","description":"The tool call this suspension resolves."},"interrupt_id":{"type":"string","description":"The sub-thread ask_user interrupt awaiting an answer."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1InterruptQuestion"},"description":"The questions the delegate is asking."}},"description":"The delegate paused on an ask_user interrupt."},"agentsV1TaskResumed":{"type":"object","properties":{"task_id":{"type":"string","description":"The delegate's sub-thread id being resumed."},"call_id":{"type":"string","description":"The resume_agent tool-call id."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"The answers to the delegate's questions."},"opaque":{"type":"string","format":"byte","description":"Provider-specific opaque blob (e.g. Gemini thought_signature)."}},"description":"The parent answered a suspended delegate (the resume_agent tool call)."},"agentsV1SleepFailed":{"type":"object","properties":{"sleep_id":{"type":"string","description":"Equal to the sleep_id of the matching SleepRequested."},"message":{"type":"string","description":"Human-readable reason the sleep was rejected; rendered into the error\ntool-result body the model sees."}},"description":"A requested sleep was rejected and will never complete. Terminal for the\nmatching SleepRequested, the failure counterpart to SleepCompleted.\nCurrently emitted when a sub-agent calls sleep (delegates cannot suspend on\ntime; the parent owns time-based pauses)."},"agentsV1EventsDeleted":{"type":"object","properties":{"from_event_id":{"type":"string","format":"uint64","description":"First event id of the deleted range (inclusive)."},"to_event_id":{"type":"string","format":"uint64","description":"Last event id of the deleted range (inclusive)."}},"description":"Notification that a contiguous range of events was deleted. The deletion is a\nsoft-delete: the events remain retrievable with include_deleted, the same\ndeletion the DeleteEvent RPC performs. Example triggers are the generation\nloop rolling a turn back and rebuilding it — the offload-and-retry rebuild, or\nRetryDriver between attempts. It carries no event id of its own and is\nbroadcast purely so live clients can drop the range from their visible view\n(and flag it deleted in their include_deleted view) the way they reconcile a\nmanual delete. On reload the server already excludes the range."},"agentsV1EventEnqueued":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the queued group, verbatim."}},"description":"A group was appended to the thread's durable queue. Broadcast-only (never\npersisted): the queue is separate store state, fetched in full via GetQueue.\nThe first event is the discriminator for the kind of deferred work."},"agentsV1QueuePriority":{"type":"string","enum":["QUEUE_PRIORITY_UNSPECIFIED","QUEUE_PRIORITY_TURN_WORK","QUEUE_PRIORITY_TRANSFER","QUEUE_PRIORITY_USER_INPUT"],"default":"QUEUE_PRIORITY_UNSPECIFIED","description":"Structural drain priority of a queued group (lower drains first).\n\n - QUEUE_PRIORITY_TURN_WORK: Deferred turn work: remote tool calls, control events, sub-agent tasks.\n - QUEUE_PRIORITY_TRANSFER: A transfer request; lands after the rest of the turn.\n - QUEUE_PRIORITY_USER_INPUT: A parked user message; drains after the whole turn."},"agentsV1EventPopped":{"type":"object","properties":{"priority":{"$ref":"#/components/schemas/agentsV1QueuePriority"},"events":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Event"},"description":"The events forming the drained group, verbatim."}},"description":"The durable queue head was drained (enacted). Broadcast-only. Carries the\ndrained group so subscribers can match-and-remove it."},"agentsV1InputArtifact":{"type":"object","properties":{"uri":{"type":"string","description":"Artifact-store URI (uploads://…, result://…, workspace://…). Never a\ndata: URI, never an external http(s) URL."},"tokens":{"type":"string","format":"uint64","description":"Token cost of the attached content, measured by the read policy at\nclearance time. Absent on events recorded before clearance carried a\ntoken count."}},"description":"A reference to an artifact-store object attached to the conversation. The\nbytes live in the artifact store; this carries only the reference. MIME type\nand filename are read from artifact-store metadata, not duplicated here.\n\nEmitted by the generation loop as part of an artifact_read tool response\nwhen the entire artifact passed the read policy: the artifact is cleared\nfor native attachment and generators resolve the URI to bytes at request\nbuild. Ingestion paths never emit it (uploads produce a Reminder)."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/events":{"get":{"summary":"Get Thread Events (Shifu, book connection)","description":"Retrieves all events from a thread.\n\nThis RPC returns the complete history of events for a thread, including\nuser inputs, assistant responses, tool calls, and their results.\nEvents are returned in chronological order.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `GetThreadEvents` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuGetThreadEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1GetEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to retrieve events from.","in":"path","required":true,"schema":{"type":"string"}},{"name":"compacted","description":"Optional. If true, return the compacted view of events.\nThe compacted view shows what the LLM sees: events in compacted ranges\nare excluded and replaced by CompactComplete events containing summaries.\nIf false (default), returns the full event history for UI display.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"include_deleted","description":"Optional. If true, include deleted events in the response.\nDeleted events will have the `deleted` field set to true on each event.","in":"query","required":false,"schema":{"type":"boolean"}}],"tags":["Agents"]}}}}
```

## Send Message (Shifu, book connection)

> Sends a message to a thread (fire and forget).\
> \
> The message is added to the thread and generation begins asynchronously.\
> Response events arrive via SubscribeThread stream or SSE, not this RPC.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`SendMessage\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the message was accepted."}},"description":"Response from sending a message."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendMessageBody":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/agentsV1UserMessage"},"interrupt_reply":{"$ref":"#/components/schemas/agentsV1InterruptReply"},"tool_approval_reply":{"$ref":"#/components/schemas/agentsV1ToolApprovalReply"}},"description":"Request to send a message to a thread."},"agentsV1UserMessage":{"type":"object","properties":{"content":{"type":"string","description":"The message text content."},"images":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserImage"},"description":"Optional images to include with the message."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1UserDocument"},"description":"Optional documents to include with the message."}},"description":"A user message with optional attachments."},"agentsV1UserImage":{"type":"object","properties":{"uri":{"type":"string","description":"URI or data URI of the image."},"detail":{"type":"string","description":"Level of detail for image processing (optional)."}},"description":"An image attached to a user message."},"agentsV1UserDocument":{"type":"object","properties":{"uri":{"type":"string","description":"Data URI of the document."},"filename":{"type":"string","description":"Original filename."}},"description":"A document attached to a user message."},"agentsV1InterruptReply":{"type":"object","properties":{"interrupt_id":{"type":"string","description":"The interrupt_id from the Interrupt event."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1QuestionAnswer"},"description":"Answers to the questions."}},"description":"User's reply to an interrupt (request type)."},"agentsV1QuestionAnswer":{"type":"object","properties":{"question_id":{"type":"string","description":"The question ID being answered."},"selected":{"type":"array","items":{"type":"string"},"description":"Selected option label(s). Multiple for multi_select questions."}},"description":"A single question's answer."},"agentsV1ToolApprovalReply":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The tool_call_id from the ToolApprovalRequested event."},"approved":{"type":"boolean","description":"True for approval, false for denial."},"reason":{"type":"string","description":"Optional reason. Populated on denial; ignored on approval."}},"description":"User's reply to a pending tool-approval request.\nPosted via SendMessageSync when the user clicks Approve or Deny on the\napproval card. The handler appends ToolApprovalGranted or\nToolApprovalDenied to the thread event log and re-enters the agent\nloop."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/input":{"post":{"summary":"Send Message (Shifu, book connection)","description":"Sends a message to a thread (fire and forget).\n\nThe message is added to the thread and generation begins asynchronously.\nResponse events arrive via SubscribeThread stream or SSE, not this RPC.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `SendMessage` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuSendMessage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendMessageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread to send the message to.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendMessageBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Stream Thread Events (Shifu, book connection)

> Subscribe to thread events via SSE\
> \
> Opens a persistent SSE connection that streams all events for the specified thread.\
> \
> \*\*Event Flow:\*\*\
> 1\. Historical events are sent first (if the thread has existing events)\
> 2\. Live events are streamed as they occur (InputText, OutputText, ToolCall\*, etc.)\
> 3\. Connection stays open until the client disconnects\
> \
> \*\*SSE Message Format:\*\*\
> Each message contains a JSON-serialized \`Event\` object in the \`data\` field:\
> \`\`\`\
> data: {"output\_text":{"text":"Hello"}}\
> \
> data: {"generation\_complete":{"usage":{"prompt\_tokens":10,"completion\_tokens":5}}}\
> \`\`\`\
> \
> \*\*Extracting Events:\*\*\
> \`\`\`javascript\
> const eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\
> eventSource.onmessage = (e) => {\
> &#x20; const event = JSON.parse(e.data);\
> &#x20; if (event.output\_text) {\
> &#x20;   console.log('Output:', event.output\_text.text);\
> &#x20; }\
> };\
> \`\`\`\
> \
> This is the browser-compatible alternative to the gRPC \`SubscribeThread\` RPC.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`StreamThreadEvents\` on \`/agents/{agent\_id}\`.

````json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/stream":{"get":{"summary":"Stream Thread Events (Shifu, book connection)","description":"Subscribe to thread events via SSE\n\nOpens a persistent SSE connection that streams all events for the specified thread.\n\n**Event Flow:**\n1. Historical events are sent first (if the thread has existing events)\n2. Live events are streamed as they occur (InputText, OutputText, ToolCall*, etc.)\n3. Connection stays open until the client disconnects\n\n**SSE Message Format:**\nEach message contains a JSON-serialized `Event` object in the `data` field:\n```\ndata: {\"output_text\":{\"text\":\"Hello\"}}\n\ndata: {\"generation_complete\":{\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5}}}\n```\n\n**Extracting Events:**\n```javascript\nconst eventSource = new EventSource('/agents/my-agent/threads/my-thread/stream');\neventSource.onmessage = (e) => {\n  const event = JSON.parse(e.data);\n  if (event.output_text) {\n    console.log('Output:', event.output_text.text);\n  }\n};\n```\n\nThis is the browser-compatible alternative to the gRPC `SubscribeThread` RPC.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `StreamThreadEvents` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuStreamThreadEvents","responses":{"200":{"description":"SSE stream of thread events","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events; each `data:` line is a JSON `agentsV1Event`."}}}},"404":{"description":"Agent or thread not found"}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","in":"path","description":"The ID of the thread to subscribe to.","required":true,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
````

## Send Tool Result (Shifu, book connection)

> Sends a tool execution result for a remote tool.\
> \
> Remote tools pause generation when called, waiting for an external system\
> to execute them and return the result via this RPC. Generation resumes\
> once the result is received.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`SendToolResult\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1SendToolResultResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"Whether the tool result was accepted and generation resumed."}},"description":"Response from sending a tool result."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsThreadServiceSendToolResultBody":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"Required. The ID of the tool call (from ToolCallStart.id)."},"content":{"$ref":"#/components/schemas/agentsV1Value"},"success":{"type":"boolean","description":"Whether the tool execution was successful."},"error":{"type":"string","description":"Error message if the tool execution failed (optional).\nWhen set, success should be false."},"duration_micros":{"type":"string","format":"uint64","description":"Duration of tool execution in microseconds (optional)."}},"description":"Request to send a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received."},"agentsV1Value":{"type":"object","properties":{"string_value":{"type":"string","description":"A string value."},"number_value":{"type":"number","format":"double","description":"A floating-point number."},"integer_value":{"type":"string","format":"int64","description":"An integer."},"bool_value":{"type":"boolean","description":"A boolean."},"binary_value":{"type":"string","format":"byte","description":"Raw binary data."},"artifact_value":{"$ref":"#/components/schemas/agentsV1ArtifactValue"},"artifact_uri_value":{"$ref":"#/components/schemas/agentsV1ArtifactUriValue"},"date_value":{"$ref":"#/components/schemas/agentsV1DateValue"},"time_value":{"$ref":"#/components/schemas/agentsV1TimeValue"},"date_time_value":{"$ref":"#/components/schemas/agentsV1DateTimeValue"},"duration_value":{"$ref":"#/components/schemas/agentsV1DurationValue"},"list_value":{"$ref":"#/components/schemas/agentsV1ListValue"},"object_value":{"$ref":"#/components/schemas/agentsV1ObjectValue"},"null_value":{"$ref":"#/components/schemas/agentsV1NullValue"}},"description":"A typed runtime value.\n\nMirrors rain_value::Value — carries both the data and enough metadata\n(mime_type, filename) for consumers to handle it correctly."},"agentsV1ArtifactValue":{"type":"object","properties":{"data":{"type":"string","format":"byte"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact value: binary data with optional metadata."},"agentsV1ArtifactUriValue":{"type":"object","properties":{"uri":{"type":"string"},"mime_type":{"type":"string"},"filename":{"type":"string"}},"description":"An artifact URI reference with optional metadata."},"agentsV1DateValue":{"type":"object","properties":{"year":{"type":"integer","format":"int32"},"month":{"type":"integer","format":"int32"},"day":{"type":"integer","format":"int32"}},"description":"A date value with year, month, day components."},"agentsV1TimeValue":{"type":"object","properties":{"hour":{"type":"integer","format":"int32"},"minute":{"type":"integer","format":"int32"},"second":{"type":"integer","format":"int32"}},"description":"A time value with hour, minute, second components."},"agentsV1DateTimeValue":{"type":"object","properties":{"rfc3339":{"type":"string"}},"description":"A date-time value as RFC3339 timestamp string.\nUsing string because google.protobuf.Timestamp only has second precision\nand RFC3339 is the canonical format used throughout this API."},"agentsV1DurationValue":{"type":"object","properties":{"seconds":{"type":"string","format":"int64"},"nanos":{"type":"integer","format":"int32"}},"description":"A duration in seconds and nanoseconds."},"agentsV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A list of values."},"agentsV1ObjectValue":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1Value"}}},"description":"A structured object with named fields."},"agentsV1NullValue":{"type":"object","description":"Placeholder for null values (oneof requires a message type)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tool-results":{"post":{"summary":"Send Tool Result (Shifu, book connection)","description":"Sends a tool execution result for a remote tool.\n\nRemote tools pause generation when called, waiting for an external system\nto execute them and return the result via this RPC. Generation resumes\nonce the result is received.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `SendToolResult` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuSendToolResult","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1SendToolResultResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The ID of the thread where the remote tool was called.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsThreadServiceSendToolResultBody"}}},"required":true},"tags":["Agents"]}}}}
```

## Create Tool Source (Shifu, book connection)

> Creates a new tool source for a thread.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`CreateToolSource\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ToolSource":{"type":"object","properties":{"source_id":{"type":"string","description":"The unique source identifier. Generated unless the creator supplied\none, as client-declared capabilities do (`client:<capability>`).","readOnly":true},"type":{"type":"string","description":"The source type (e.g., \"rust\", \"grpc\", \"memory\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable label for the source type.","readOnly":true},"description":{"type":"string","description":"Description of this tool source.","readOnly":true},"config":{"type":"object","description":"The current configuration of this source.","readOnly":true},"tool_adapters":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/agentsV1ToolAdapterChain"},"description":"Per-tool adapter chains.\nKey is tool ID (stable hash of original tool name), value is the ordered chain of adapters.\nAdapters are applied in order: first adapter wraps the tool,\nsecond adapter wraps the first, etc."}},"description":"A configured tool source belonging to an agent."},"agentsV1ToolAdapterChain":{"type":"object","properties":{"adapters":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ToolAdapterDescriptor"},"description":"List of adapters applied to this tool."}},"description":"A chain of adapters for a single tool.\nAdapters are applied in order: first adapter wraps the tool,\nsecond adapter wraps the first, etc."},"agentsV1ToolAdapterDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this adapter (nanoid, server-generated).","readOnly":true},"kind":{"type":"string","description":"The adapter kind name (e.g., \"jq\").","readOnly":true},"display_name":{"type":"string","description":"Human-readable display name (e.g., \"JQ Transform\").","readOnly":true},"config":{"type":"object","title":"The adapter configuration as a generic struct.\nStructure depends on the kind:\n- \"jq\": {input?: string, output?: string}"}},"description":"Descriptor for a tool adapter instance.\nUsed in list responses, mutation responses, and adapter chains."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsToolCatalogServiceCreateToolSourceBody":{"type":"object","properties":{"type":{"type":"string","description":"Required. The tool source type (e.g., \"rust\", \"grpc\")."},"config":{"type":"object","description":"Required. Configuration for the tool source.\nKeys and values depend on the type's config_fields."},"source_id":{"type":"string","description":"Optional. The id to give the source, instead of a generated one.\n\nFor client-declared capabilities, which name their source `client.<id>`\nso that toggling one off can address it and toggling it on twice cannot\nproduce two copies. Rejected when a source already holds the id, and\nrejected if it contains ':' — that character is reserved for custom\nmethods in resource paths, so an id carrying one could never be\naddressed again."}},"description":"Request message for CreateToolSource.","required":["type","config"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tool-sources":{"post":{"summary":"Create Tool Source (Shifu, book connection)","description":"Creates a new tool source for a thread.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `CreateToolSource` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuCreateToolSource","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ToolSource"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread that owns this resource.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsToolCatalogServiceCreateToolSourceBody"}}},"required":true},"tags":["Agents"]}}}}
```

## List Tools (Shifu, book connection)

> Lists the flat tool catalog for a thread (one entry per enabled\
> tool across all sources). Reflects per-thread enablement and\
> adapter overrides; the agent's read-only base catalog is exposed\
> by \`DiffTools.base\`.\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`ListTools\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ListToolsResponse":{"type":"object","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Tool"},"description":"The tools available to the agent."},"is_customized":{"type":"boolean","description":"Whether this represents a per-thread tool-level override. True\nwhen the flat (source, tool, name, adapters, metadata) view\ndiffers from the pinned agent version's tools. Independent of\n`ListToolSources.is_customized`, which only flags source-identity\nchanges."}},"description":"Response message for ListTools."},"agentsV1Tool":{"type":"object","properties":{"id":{"type":"string","description":"Globally unique, stable tool identifier (hash of the original tool name).\nUse this to target a tool in requests. Remains constant even when the\ntool is renamed via adapters.","readOnly":true},"name":{"type":"string","description":"Human-facing display name. May change due to adapters.\nDo not use for lookup, routing, or invocation — use `id` instead.","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool. Can be used as a performance hint\nin requests to limit search scope.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted (has adapters applied).","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations, if different).","readOnly":true},"original_description":{"type":"string","description":"The original description (before any adaptations).","readOnly":true},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\".","readOnly":true},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ToolParameter"},"description":"Typed parameters for this tool (adapted version, as seen by LLM).","readOnly":true},"output":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"is_remote":{"type":"boolean","description":"Whether the tool requires remote execution. When true, generation\npauses on each call and waits for an external result via the\nSendToolResult API. Reflects the effective (post-adapter) value.","readOnly":true},"requires_approval":{"type":"boolean","description":"Whether the tool requires explicit user approval before each call.\nWhen true, the agent loop pauses on the tool call and waits for the\nuser to Approve or Deny. Reflects the effective (post-adapter) value.","readOnly":true},"initial_window_seconds":{"type":"integer","format":"int64","description":"How many seconds an unclaimed remote call has to be answered before it is\nclosed out, zero meaning it never expires. Only meaningful when is_remote\nis true. Reflects the effective (post-adapter) value.","readOnly":true},"lease_window_seconds":{"type":"integer","format":"int64","description":"How many seconds a claim holds a remote call open past each renewal, zero\nmeaning it never expires. Only meaningful when is_remote is true.\nReflects the effective (post-adapter) value.","readOnly":true},"execution_window_seconds":{"type":"integer","format":"int64","description":"How many seconds a local call may run before it is abandoned and reported\nas a timeout, zero meaning it is never abandoned. Only meaningful when\nis_remote is false. Reflects the effective (post-adapter) value.","readOnly":true}},"description":"A tool that can be called by an AI agent."},"agentsV1ToolParameter":{"type":"object","properties":{"name":{"type":"string","description":"The parameter name.","readOnly":true},"description":{"type":"string","description":"Human-readable description of the parameter.","readOnly":true},"value_type":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"required":{"type":"boolean","description":"Whether this parameter is required.","readOnly":true}},"description":"A tool parameter with semantic type information."},"agentsV1ValueTypeDescriptor":{"type":"object","properties":{"string_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"number_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"integer_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"boolean_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"binary_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"artifact_type":{"$ref":"#/components/schemas/agentsV1ArtifactValueType"},"artifact_uri_type":{"$ref":"#/components/schemas/agentsV1ArtifactValueType"},"literal_string_type":{"$ref":"#/components/schemas/agentsV1LiteralStringType"},"date_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"time_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"date_time_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"duration_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"list_type":{"$ref":"#/components/schemas/agentsV1ListType"},"object_type":{"$ref":"#/components/schemas/agentsV1ObjectType"},"dictionary_type":{"$ref":"#/components/schemas/agentsV1DictionaryType"},"optional_type":{"$ref":"#/components/schemas/agentsV1OptionalType"},"enum_type":{"$ref":"#/components/schemas/agentsV1EnumType"},"any_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"null_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"description":{"type":"string","description":"Optional description of this value type."}},"description":"Semantic type descriptor for tool parameters and outputs.\n\nRepresents the semantic meaning of a value type, enabling type-appropriate\nUI widgets beyond what raw JSON Schema can express."},"agentsV1EmptyType":{"type":"object","description":"Empty placeholder for simple types that have no additional configuration."},"agentsV1ArtifactValueType":{"type":"object","properties":{"mime_types":{"type":"array","items":{"type":"string"},"description":"Accepted MIME types (e.g., \"text/csv\", \"application/vnd.apache.parquet\").\nEmpty means any MIME type is accepted."}},"description":"An artifact or artifact URI value type with optional MIME type constraints."},"agentsV1LiteralStringType":{"type":"object","properties":{"value":{"type":"string","description":"The constant string value."}},"description":"A literal string constant."},"agentsV1ListType":{"type":"object","properties":{"items":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"}},"description":"A list/array type."},"agentsV1ObjectType":{"type":"object","properties":{"properties":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ObjectPropertyDescriptor"},"description":"The properties of the object."}},"description":"A structured object type with named properties."},"agentsV1ObjectPropertyDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"The property name."},"value_type":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"required":{"type":"boolean","description":"Whether this property is required."}},"description":"A named property within an object type."},"agentsV1DictionaryType":{"type":"object","properties":{"keys":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"values":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"}},"description":"A dictionary/map type."},"agentsV1OptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"}},"description":"An optional value type."},"agentsV1EnumType":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"description":"The possible variant types."}},"description":"A union/enum type with multiple possible variants.\n\nAlways normalised on construction: at least two variants, distinct under\nstructural equality, no nested enums, no `Any` member (`Any` absorbs every\nenum), and `Null` is canonicalised into `OptionalType` rather than\nappearing as a member."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tools":{"get":{"summary":"List Tools (Shifu, book connection)","description":"Lists the flat tool catalog for a thread (one entry per enabled\ntool across all sources). Reflects per-thread enablement and\nadapter overrides; the agent's read-only base catalog is exposed\nby `DiffTools.base`.\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `ListTools` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuListTools","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ListToolsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread context for variable resolution.","in":"path","required":true,"schema":{"type":"string"}},{"name":"source_id","description":"Optional. Filter by source ID.","in":"query","required":false,"schema":{"type":"string"}},{"name":"name_query","description":"Optional. Search query for tool name (case-insensitive contains).","in":"query","required":false,"schema":{"type":"string"}},{"name":"description_query","description":"Optional. Search query for tool description (case-insensitive contains).","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Agents"]}}}}
```

## Enable Tools (Shifu, book connection)

> Enables multiple tools in a source on a thread (additive).\
> \
> Targets the built-in \`shifu\` agent in the book connection scope; the generic form is \`EnableTools\` on \`/agents/{agent\_id}\`.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Build and version agents, and talk to them through threads (send input, stream events, manage artifacts and plans). Covers the workspace Agent Builder and the built-in agents scoped to automations, runs and books."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"agentsV1ToolEnablement":{"type":"object","properties":{"source_id":{"type":"string","description":"The tool source this enablement applies to.","readOnly":true},"tools":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1Tool"},"description":"Enabled tools with their descriptor snapshots. Order is not\nsignificant."}},"description":"Which tools from one source are enabled for the agent or thread.\n\nThe source describes what tools exist; the enablement describes what\nis turned on. An absent enablement (or an empty `tools` list) means no\ntools from that source are exposed to the LLM."},"agentsV1Tool":{"type":"object","properties":{"id":{"type":"string","description":"Globally unique, stable tool identifier (hash of the original tool name).\nUse this to target a tool in requests. Remains constant even when the\ntool is renamed via adapters.","readOnly":true},"name":{"type":"string","description":"Human-facing display name. May change due to adapters.\nDo not use for lookup, routing, or invocation — use `id` instead.","readOnly":true},"description":{"type":"string","description":"Human-readable description of what the tool does.","readOnly":true},"source_id":{"type":"string","description":"The source that provides this tool. Can be used as a performance hint\nin requests to limit search scope.","readOnly":true},"is_adapted":{"type":"boolean","description":"Whether this tool has been adapted (has adapters applied).","readOnly":true},"original_name":{"type":"string","description":"The original tool name (before any adaptations, if different).","readOnly":true},"original_description":{"type":"string","description":"The original description (before any adaptations).","readOnly":true},"status_template":{"type":"string","description":"Optional status template for UI display during tool execution.\nSupports argument interpolation using ${arg} or $arg syntax.\nExample: \"Reading ${uri}\" becomes \"Reading /path/to/file.txt\".","readOnly":true},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ToolParameter"},"description":"Typed parameters for this tool (adapted version, as seen by LLM).","readOnly":true},"output":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"is_remote":{"type":"boolean","description":"Whether the tool requires remote execution. When true, generation\npauses on each call and waits for an external result via the\nSendToolResult API. Reflects the effective (post-adapter) value.","readOnly":true},"requires_approval":{"type":"boolean","description":"Whether the tool requires explicit user approval before each call.\nWhen true, the agent loop pauses on the tool call and waits for the\nuser to Approve or Deny. Reflects the effective (post-adapter) value.","readOnly":true},"initial_window_seconds":{"type":"integer","format":"int64","description":"How many seconds an unclaimed remote call has to be answered before it is\nclosed out, zero meaning it never expires. Only meaningful when is_remote\nis true. Reflects the effective (post-adapter) value.","readOnly":true},"lease_window_seconds":{"type":"integer","format":"int64","description":"How many seconds a claim holds a remote call open past each renewal, zero\nmeaning it never expires. Only meaningful when is_remote is true.\nReflects the effective (post-adapter) value.","readOnly":true},"execution_window_seconds":{"type":"integer","format":"int64","description":"How many seconds a local call may run before it is abandoned and reported\nas a timeout, zero meaning it is never abandoned. Only meaningful when\nis_remote is false. Reflects the effective (post-adapter) value.","readOnly":true}},"description":"A tool that can be called by an AI agent."},"agentsV1ToolParameter":{"type":"object","properties":{"name":{"type":"string","description":"The parameter name.","readOnly":true},"description":{"type":"string","description":"Human-readable description of the parameter.","readOnly":true},"value_type":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"required":{"type":"boolean","description":"Whether this parameter is required.","readOnly":true}},"description":"A tool parameter with semantic type information."},"agentsV1ValueTypeDescriptor":{"type":"object","properties":{"string_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"number_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"integer_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"boolean_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"binary_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"artifact_type":{"$ref":"#/components/schemas/agentsV1ArtifactValueType"},"artifact_uri_type":{"$ref":"#/components/schemas/agentsV1ArtifactValueType"},"literal_string_type":{"$ref":"#/components/schemas/agentsV1LiteralStringType"},"date_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"time_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"date_time_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"duration_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"list_type":{"$ref":"#/components/schemas/agentsV1ListType"},"object_type":{"$ref":"#/components/schemas/agentsV1ObjectType"},"dictionary_type":{"$ref":"#/components/schemas/agentsV1DictionaryType"},"optional_type":{"$ref":"#/components/schemas/agentsV1OptionalType"},"enum_type":{"$ref":"#/components/schemas/agentsV1EnumType"},"any_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"null_type":{"$ref":"#/components/schemas/agentsV1EmptyType"},"description":{"type":"string","description":"Optional description of this value type."}},"description":"Semantic type descriptor for tool parameters and outputs.\n\nRepresents the semantic meaning of a value type, enabling type-appropriate\nUI widgets beyond what raw JSON Schema can express."},"agentsV1EmptyType":{"type":"object","description":"Empty placeholder for simple types that have no additional configuration."},"agentsV1ArtifactValueType":{"type":"object","properties":{"mime_types":{"type":"array","items":{"type":"string"},"description":"Accepted MIME types (e.g., \"text/csv\", \"application/vnd.apache.parquet\").\nEmpty means any MIME type is accepted."}},"description":"An artifact or artifact URI value type with optional MIME type constraints."},"agentsV1LiteralStringType":{"type":"object","properties":{"value":{"type":"string","description":"The constant string value."}},"description":"A literal string constant."},"agentsV1ListType":{"type":"object","properties":{"items":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"}},"description":"A list/array type."},"agentsV1ObjectType":{"type":"object","properties":{"properties":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ObjectPropertyDescriptor"},"description":"The properties of the object."}},"description":"A structured object type with named properties."},"agentsV1ObjectPropertyDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"The property name."},"value_type":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"required":{"type":"boolean","description":"Whether this property is required."}},"description":"A named property within an object type."},"agentsV1DictionaryType":{"type":"object","properties":{"keys":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"values":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"}},"description":"A dictionary/map type."},"agentsV1OptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"}},"description":"An optional value type."},"agentsV1EnumType":{"type":"object","properties":{"variants":{"type":"array","items":{"$ref":"#/components/schemas/agentsV1ValueTypeDescriptor"},"description":"The possible variant types."}},"description":"A union/enum type with multiple possible variants.\n\nAlways normalised on construction: at least two variants, distinct under\nstructural equality, no nested enums, no `Any` member (`Any` absorbs every\nenum), and `Null` is canonicalised into `OptionalType` rather than\nappearing as a member."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"agentsToolCatalogServiceEnableToolsBody":{"type":"object","properties":{"tool_ids":{"type":"array","items":{"type":"string"},"description":"Required. The tool IDs to enable (added to existing enabled set).\nTool IDs are stable hashes of the original tool name."}},"description":"Request message for EnableTools (batch enable, additive).","required":["tool_ids"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/versions/{book_version}/connections/{connection_id}/agents/shifu/threads/{thread_id}/tools/{tool_source_id}:enable":{"post":{"summary":"Enable Tools (Shifu, book connection)","description":"Enables multiple tools in a source on a thread (additive).\n\nTargets the built-in `shifu` agent in the book connection scope; the generic form is `EnableTools` on `/agents/{agent_id}`.","operationId":"BookConnectionShifuEnableTools","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsV1ToolEnablement"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread_id","description":"Required. The thread that owns this resource.","in":"path","required":true,"schema":{"type":"string"}},{"name":"tool_source_id","description":"Required. The source ID containing the tools.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/agentsToolCatalogServiceEnableToolsBody"}}},"required":true},"tags":["Agents"]}}}}
```
