> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Team

> Update a team's configuration, name, description, or status.

Supports partial updates - only provided fields are updated.
Validates member_ids if configuration is being updated.
Only allows updating teams belonging to the current organization.



## OpenAPI

````yaml https://control-plane.kubiya.ai/api/openapi.json patch /api/v1/teams/{team_id}
openapi: 3.1.0
info:
  title: Agent Control Plane API
  description: Multi-tenant agent orchestration with Temporal workflows
  version: 1.0.0
servers: []
security:
  - BearerAuth: []
tags:
  - name: health
    description: 🏥 **Health & Status** - Check API health and availability
  - name: authentication
    description: 🔐 **Authentication** - Token validation and auth management
  - name: agents
    description: 🤖 **Agents** - Create and manage AI agents with custom capabilities
  - name: skills
    description: 🛠️ **Tool Sets** - Manage agent skills and tool configurations
  - name: integrations
    description: 🔌 **Integrations** - Connect to external services (Kubiya managed)
  - name: custom-integrations
    description: >-
      ⚙️ **Custom Integrations** - User-defined integration instances with env
      vars, secrets, and files
  - name: integration-templates
    description: >-
      📦 **Integration Templates** - Pre-configured templates for common
      services (PostgreSQL, Redis, MongoDB, etc.)
  - name: secrets
    description: 🔑 **Secrets** - Secure credential storage and retrieval
  - name: teams
    description: 👥 **Teams** - Team management and collaboration
  - name: workflows
    description: 📊 **Workflows** - Multi-step automation and orchestration
  - name: executions
    description: ▶️ **Executions** - Track and monitor workflow runs
  - name: jobs
    description: ⏰ **Jobs** - Scheduled and webhook-triggered tasks
  - name: policies
    description: 🛡️ **Policies** - Access control and security policies
  - name: analytics
    description: 📈 **Analytics** - Usage metrics and performance monitoring
  - name: projects
    description: 📁 **Projects** - Project organization and management
  - name: environments
    description: 🌍 **Environments** - Environment configuration (dev, staging, prod)
  - name: models
    description: 🧠 **Models** - LLM model configuration and management
  - name: runtimes
    description: ⚡ **Runtimes** - Agent execution runtime environments
  - name: workers
    description: 👷 **Workers** - Worker registration and heartbeat monitoring
  - name: storage
    description: 💾 **Storage** - File storage and cloud integration
  - name: context-graph
    description: 🕸️ **Context Graph** - Knowledge graph and context management
  - name: temporal-workflows
    description: >-
      ⚙️ **Temporal Workflows** - Background workflows for context graph
      ingestion, connector operations, and scheduled jobs
  - name: templates
    description: 📝 **Templates** - Reusable configuration templates
paths:
  /api/v1/teams/{team_id}:
    patch:
      summary: Update Team
      description: |-
        Update a team's configuration, name, description, or status.

        Supports partial updates - only provided fields are updated.
        Validates member_ids if configuration is being updated.
        Only allows updating teams belonging to the current organization.
      operationId: update_team_api_v1_teams__team_id__patch
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: string
            title: Team Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TeamUpdate:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: 'null'
          title: Name
          description: Team name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Team description
        status:
          anyOf:
            - $ref: '#/components/schemas/TeamStatus'
            - type: 'null'
          description: Team status
        runtime:
          anyOf:
            - type: string
            - type: 'null'
          title: Runtime
          description: 'Runtime type: ''default'' (Agno) or ''claude_code'' (Claude Code SDK)'
        configuration:
          anyOf:
            - $ref: '#/components/schemas/TeamConfiguration'
            - type: 'null'
          description: Team configuration
        skill_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Skill Ids
        skill_configurations:
          anyOf:
            - additionalProperties:
                additionalProperties: true
                type: object
              type: object
            - type: 'null'
          title: Skill Configurations
        environment_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Environment Ids
        execution_environment:
          anyOf:
            - $ref: '#/components/schemas/ExecutionEnvironment'
            - type: 'null'
      type: object
      title: TeamUpdate
      description: Update an existing team
    TeamResponse:
      properties:
        id:
          type: string
          title: Id
        organization_id:
          type: string
          title: Organization Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        status:
          $ref: '#/components/schemas/TeamStatus'
        runtime:
          type: string
          title: Runtime
          description: >-
            Runtime type for team leader: 'default' (Agno) or 'claude_code'
            (Claude Code SDK)
          default: default
        configuration:
          $ref: '#/components/schemas/TeamConfiguration'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        projects:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Projects
          description: Projects this team belongs to
        skill_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Skill Ids
          description: IDs of associated skills
        skills:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Skills
          description: Associated skills with details
        execution_environment:
          anyOf:
            - $ref: '#/components/schemas/ExecutionEnvironment'
            - type: 'null'
      type: object
      required:
        - id
        - organization_id
        - name
        - description
        - status
        - configuration
        - created_at
        - updated_at
      title: TeamResponse
      description: Team response with structured configuration
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TeamStatus:
      type: string
      enum:
        - active
        - inactive
        - archived
        - idle
      title: TeamStatus
      description: Team status enumeration
    TeamConfiguration:
      properties:
        member_ids:
          items:
            type: string
          type: array
          title: Member Ids
          description: List of agent IDs in the team
        instructions:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
          title: Instructions
          description: >-
            Instructions for the team - can be a single string or list of
            instructions
          default: ''
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ReasoningConfig'
            - type: 'null'
          description: Reasoning configuration
        llm:
          anyOf:
            - $ref: '#/components/schemas/LLMConfig'
            - type: 'null'
          description: LLM configuration for the team
        tools:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Tools
          description: Tools available to the team - list of tool configurations
        knowledge_base:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Knowledge Base
          description: Knowledge base configuration (vector store, embeddings, etc.)
        session:
          anyOf:
            - $ref: '#/components/schemas/SessionConfig'
            - type: 'null'
          description: Session configuration
        dependencies:
          additionalProperties: true
          type: object
          title: Dependencies
          description: External dependencies (databases, APIs, services)
        markdown:
          type: boolean
          title: Markdown
          description: Enable markdown formatting in responses
          default: true
        add_datetime_to_instructions:
          type: boolean
          title: Add Datetime To Instructions
          description: Automatically add current datetime to instructions
          default: false
        structured_outputs:
          type: boolean
          title: Structured Outputs
          description: Enable structured outputs
          default: false
        response_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Response Model
          description: Response model schema name
        debug_mode:
          type: boolean
          title: Debug Mode
          description: Enable debug mode with verbose logging
          default: false
        monitoring:
          type: boolean
          title: Monitoring
          description: Enable monitoring and telemetry
          default: false
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Additional custom metadata for the team
      type: object
      title: TeamConfiguration
      description: >-
        Comprehensive team configuration aligned with Agno's Team capabilities.

        This allows full control over team behavior, reasoning, tools, and LLM
        settings.
    ExecutionEnvironment:
      properties:
        working_dir:
          anyOf:
            - type: string
            - type: 'null'
          title: Working Dir
          description: Working directory for execution (overrides default workspace)
        env_vars:
          additionalProperties:
            type: string
          type: object
          title: Env Vars
          description: Environment variables (key-value pairs)
        secrets:
          items:
            type: string
          type: array
          title: Secrets
          description: Secret names from Kubiya vault
        integration_ids:
          items:
            type: string
          type: array
          title: Integration Ids
          description: Integration UUIDs for delegated credentials
        mcp_servers:
          additionalProperties:
            $ref: '#/components/schemas/MCPServerConfig'
          type: object
          title: Mcp Servers
          description: >-
            MCP (Model Context Protocol) server configurations. Supports stdio,
            HTTP, and SSE transports.
      type: object
      title: ExecutionEnvironment
      description: Execution environment configuration for agents/teams
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ReasoningConfig:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: Enable reasoning for the team
          default: false
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Model to use for reasoning
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Agent ID to use for reasoning
        min_steps:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Min Steps
          description: Minimum reasoning steps
          default: 1
        max_steps:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 1
            - type: 'null'
          title: Max Steps
          description: Maximum reasoning steps
          default: 10
      type: object
      title: ReasoningConfig
      description: Reasoning configuration for the team
    LLMConfig:
      properties:
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Default model for the team
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: Temperature for generation
        max_tokens:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Tokens
          description: Maximum tokens to generate
        top_p:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Top P
          description: Top-p sampling
        top_k:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Top K
          description: Top-k sampling
        stop:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop
          description: Stop sequences
        frequency_penalty:
          anyOf:
            - type: number
              maximum: 2
              minimum: -2
            - type: 'null'
          title: Frequency Penalty
          description: Frequency penalty
        presence_penalty:
          anyOf:
            - type: number
              maximum: 2
              minimum: -2
            - type: 'null'
          title: Presence Penalty
          description: Presence penalty
      type: object
      title: LLMConfig
      description: LLM configuration for the team
    SessionConfig:
      properties:
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: User ID for the session
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: Session ID
        auto_save:
          type: boolean
          title: Auto Save
          description: Auto-save session state
          default: true
        persist:
          type: boolean
          title: Persist
          description: Persist session across runs
          default: true
      type: object
      title: SessionConfig
      description: Session configuration for the team
    MCPServerConfig:
      properties:
        command:
          anyOf:
            - type: string
            - type: 'null'
          title: Command
          description: Command for stdio transport (mutually exclusive with url/type)
        args:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Args
          description: Arguments for stdio transport
        env:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Env
          description: Environment variables (used by both stdio and HTTP transports)
        transport_type:
          anyOf:
            - type: string
              enum:
                - http
                - sse
            - type: 'null'
          title: Transport Type
          description: Transport type for HTTP/SSE (mutually exclusive with command)
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: URL for HTTP/SSE transport (mutually exclusive with command)
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Headers
          description: HTTP headers for HTTP/SSE transport
      type: object
      title: MCPServerConfig
      description: >-
        Unified MCP server configuration supporting multiple transport types.


        This schema uses discriminated union based on the presence of 'command'
        or 'type' field:

        - If 'command' is present: stdio transport

        - If 'type' is present: HTTP/SSE transport


        The configuration is validated to ensure only one transport type is
        specified.
      examples:
        - args:
            - '-m'
            - mcp_server_filesystem
          command: python
          env:
            ALLOWED_PATHS: '{{.env.PROJECT_ROOT}}'
        - headers:
            Authorization: Bearer {{.secret.token}}
          type: sse
          url: https://api.example.com/mcp
        - headers:
            Authorization: Bearer {{.secret.token}}
          transport_type: sse
          url: https://api.example.com/mcp
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your Kubiya API token (format: Bearer <token>)'

````