--- title: "Create an assistant (agent + workflow) as one unit" method: POST path: "/v1/assistants" tags: ["assistants"] --- # Create an assistant (agent + workflow) as one unit `POST /v1/assistants` Create an assistant (agent + parent workflow) with an inactive initial revision in one transaction. Activate explicitly to go live. ## Request body - AssistantCreateComposite — Request body for POST /assistants — create an agent + workflow as one unit. Q1: every assistant gets a workflow shell at creation; an empty flow (``instructions=""``) is legal and runs the bare-agent path. - `name` string, required - `description` string, nullable - `persona` string, nullable - `system_prompt` string, nullable - `system_context_variables` SystemContextVariableSpec[], nullable - `name` string, required - `type` 'string' | 'int' | 'float' | 'bool' | 'enum', required - `enum_values` string[], nullable - `description` string, nullable - `context_variables` LegacySystemContextVariableSpec[], nullable — Deprecated alias for system_context_variables. - `name` string, required - `type` 'string' | 'int' | 'float' | 'bool' | 'enum', required - `enum_values` string[], nullable - `description` string, nullable - `source` 'system', nullable - `reask_cap` unknown - `variable_defaults` object, nullable - `channel_specific_config` object, nullable - `router_config_id` string, uuid, nullable - `model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `current_time` CurrentTimeSettings — One tier's optional current-time overrides. ``None`` means inherit for that field. An empty object therefore clears the tier and inherits both values. The API stores only non-null fields. - `enabled` boolean, nullable - `timezone` string, nullable - `analyzer_model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `memory_enabled` boolean — Enable semantic memory recall and ingestion for this revision. - `router_model_settings` object, nullable - `metadata` object, nullable - `kb_clearance_level` integer, nullable - `kb_audience_tags` string[], nullable - `knowledge_gap_analysis_enabled` boolean - `tool_refs` ToolRef[], nullable - `kind` 'api' | 'integration' | 'util' | 'kb', required - `id` string, nullable - `slug` string, nullable - `output_bindings` object, nullable - `input_defaults` object, nullable - `knowledge_base_refs` KnowledgeBaseRef[], nullable - `id` string, required - `description` string, nullable - `clearance_level` integer, nullable - `instructions` string - `workflow_description` string, nullable ## Response `201` Successful Response - AssistantCompositeResponse — Response for POST /assistants — the created agent + workflow. - `agent` AgentResponse, required - `id` string, uuid, required - `organization_id` string, uuid, required - `name` string, required - `description` string, nullable - `active_revision_id` string, uuid, nullable - `active_revision` AgentRevisionResponse - `id` string, uuid, required - `agent_id` string, uuid, required - `name` string, required - `description` string, nullable - `persona` string, nullable - `system_prompt` string, nullable - `context_variables` ContextVarSpec[], nullable — Deprecated legacy projection; contains assistant SYSTEM declarations only. Use system_context_variables. - `name` string, required - `type` 'string' | 'int' | 'float' | 'bool' | 'enum', required - `source` 'system' | 'derived' - `enum_values` string[], nullable - `reask_cap` integer, nullable - `description` string, nullable - `variable_defaults` object, nullable - `tool_refs` object[], nullable - `knowledge_base_refs` object[], nullable - `platform_tools` object - `policies_enabled` boolean - `policy_refs` object[], nullable - `channel_specific_config` object, nullable - `router_config_id` string, uuid, nullable - `model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `analyzer_model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `workflow_enabled` boolean - `memory_enabled` boolean - `current_time` CurrentTimeSettings — One tier's optional current-time overrides. ``None`` means inherit for that field. An empty object therefore clears the tier and inherits both values. The API stores only non-null fields. - `enabled` boolean, nullable - `timezone` string, nullable - `kb_clearance_level` integer, nullable - `kb_audience_tags` string[] - `continue_after_flow` boolean, nullable - `voice_call_settings` object, nullable - `created_by` string, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `published_at` string, date-time, nullable - `system_context_variables` SystemContextVariableSpec[], nullable, required — Assistant-owned immutable inputs. Derived variables belong to workflows. - `name` string, required - `type` 'string' | 'int' | 'float' | 'bool' | 'enum', required - `enum_values` string[], nullable - `description` string, nullable - `metadata` object - `platform_tools` object - `knowledge_gap_analysis_enabled` boolean - `release_suite_id` string, uuid, nullable - `release_gate_mode` 'off' | 'advisory' — Per-agent release-gate mode (ENG-727). ``off`` = no release checks; ``advisory`` = compute + display a verdict but never block activation. The gate always runs and surfaces a verdict; it never refuses activation. - `release_gate_max_failures` integer - `max_active_calls` integer, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `agent_revision` AgentRevisionResponse, required - `id` string, uuid, required - `agent_id` string, uuid, required - `name` string, required - `description` string, nullable - `persona` string, nullable - `system_prompt` string, nullable - `context_variables` ContextVarSpec[], nullable — Deprecated legacy projection; contains assistant SYSTEM declarations only. Use system_context_variables. - `name` string, required - `type` 'string' | 'int' | 'float' | 'bool' | 'enum', required - `source` 'system' | 'derived' - `enum_values` string[], nullable - `reask_cap` integer, nullable - `description` string, nullable - `variable_defaults` object, nullable - `tool_refs` object[], nullable - `knowledge_base_refs` object[], nullable - `platform_tools` object - `policies_enabled` boolean - `policy_refs` object[], nullable - `channel_specific_config` object, nullable - `router_config_id` string, uuid, nullable - `model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `analyzer_model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `workflow_enabled` boolean - `memory_enabled` boolean - `current_time` CurrentTimeSettings — One tier's optional current-time overrides. ``None`` means inherit for that field. An empty object therefore clears the tier and inherits both values. The API stores only non-null fields. - `enabled` boolean, nullable - `timezone` string, nullable - `kb_clearance_level` integer, nullable - `kb_audience_tags` string[] - `continue_after_flow` boolean, nullable - `voice_call_settings` object, nullable - `created_by` string, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `published_at` string, date-time, nullable - `system_context_variables` SystemContextVariableSpec[], nullable, required — Assistant-owned immutable inputs. Derived variables belong to workflows. - `name` string, required - `type` 'string' | 'int' | 'float' | 'bool' | 'enum', required - `enum_values` string[], nullable - `description` string, nullable - `workflow` WorkflowResponse, required - `id` string, uuid, required - `organization_id` string, uuid, required - `name` string, required - `description` string, nullable - `kind` string - `active_revision_id` string, uuid, nullable - `active_revision` WorkflowRevisionResponse — Full revision response — the compile-poll target (WF-08). Clients poll GET /workflows/revisions/{id} and read ``compilation_status`` + ``compilation_errors`` + ``compiled_graph`` to determine whether an async compile job is done. ``compilation_task_id`` is the Celery task handle the conductor uses to cancel an in-flight compile. - `id` string, uuid, required - `workflow_id` string, uuid, required - `name` string, required - `description` string, nullable - `instructions` string, required - `compiled_graph` object, nullable - `executable_graph` object, nullable - `quality_report` object, nullable - `compilation_errors` string[], nullable - `compilation_strategy` string, required - `compilation_status` string, required - `compilation_task_id` string, nullable - `compilation_input_hash` string, nullable - `trigger_type` string, required - `trigger_config` object, required - `router_config_id` string, uuid, nullable - `analyzer_model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `router_model_settings` ModelChainEntry - `model` string, required - `config` ModelConfig - `temperature` number, nullable - `max_tokens` integer, nullable - `top_p` number, nullable - `stop_sequences` string[], nullable - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable - `request_timeout_ms` integer, nullable - `thinking_budget` integer, nullable - `policy_ids` unknown[] - unknown - `tool_input_defaults` object, nullable - `tools` WorkflowToolResponse[] - `tool` ToolResponse, required - `id` string, uuid, required - `organization_id` string, uuid, required - `name` string, required - `description` string, nullable, required - `tool_type` 'api_call' | 'call_transfer', required - `active_revision_id` string, uuid, nullable, required - `active_revision` ToolRevisionResponse - `id` string, uuid, required - `tool_id` string, uuid, required - `name` string, required - `description` string, nullable, required - `configuration` APICallConfiguration — Configuration for an API_CALL tool, stored in Tool.configuration. Supports ``{{variable}}`` placeholders in url, headers, and body that are resolved at execution time from the tool's input variables and runtime metadata (via ``{{metadata.key}}``). - … - `transfer_target` TransferTargetView — A call_transfer revision's stored target, surfaced on reads. ``ToolRevisionResponse.configuration`` is api_call-typed and parses to ``None`` for a transfer config (it has no ``url``), so this field carries the destination/mode back for the transfer-target picker. ``label`` / ``when_to_use`` come from the parent Tool's ``name`` / ``description``. Either ``destination`` (static) or ``destination_source`` (api_tool dynamic) is present, never both. The unused variant is omitted from serialization. - … - `response_schema` ResponseFieldSelector — The projection applied to a tool response. - … - `status` string, required - `has_secrets` boolean - `input_defaults` object, nullable - `compatibility` ToolCompatibilityReportResponse — Impact report shared by preflight analysis and successful promotion. Pre-prod: findings are advisory warnings — promotion always succeeds. The ``has_blocking`` / ``active_blocking_*`` fields retain their literal blocking semantics (and therefore remain false/zero today). - … - `created_by` string, nullable, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `default_count` integer, required — How many input variables carry an operator *default* (ENG-590). - `pinned_count` integer, required — How many input variables are operator-*pinned* (ENG-590). - `stale_input_fields` string[], required — Configured variables removed/renamed/retyped by an operator edit. - `merged_input_preview` object, required — The input schema with each operator value injected as ``default``. - `metadata` object - `created_at` string, date-time, required - `updated_at` string, date-time, required - `knowledge_base_ids` string[] - `created_by` string, nullable - `created_at` string, date-time, required - `updated_at` string, date-time, required - `graph_version` integer - `warnings` string[] - `metadata` object - `created_at` string, date-time, required - `updated_at` string, date-time, required - `workflow_revision_id` string, uuid, required ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/oneloop-hq/apis/feather-api.md) · [All operations](https://skmtc.net/oneloop-hq/apis/feather-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneloop-hq/feather-api/revisions/9cd7291d4228/schema)