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

# Create a new agent pool

> Creates an inactive agent pool and its membership atomically. All member agents must exist in the workspace. An empty description, empty membership, or duplicate member rejects the request.



## OpenAPI

````yaml https://openapi.cadenya.com/api-spec.yml post /v1/workspaces/{workspaceId}/agent_pools
openapi: 3.1.0
info:
  title: Cadenya API
  description: API for the Cadenya Agent Runtime platform.
  version: '1.0'
servers:
  - url: https://api.cadenya.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: AIProviderKeyService
  - name: APIKeyService
    description: |-
      Issue, rotate, disable, and revoke the account's API keys. Keys belong to
       the account and reach the workspaces they are assigned to, or every
       workspace when all_workspaces is set. Creating or changing an
       all-workspaces key also requires the api_keys:admin scope, and a
       caller may only assign workspaces it can access itself and operate on keys
       whose scopes it holds.
  - name: AccountService
    description: >-
      Manage the authenticated account. Accounts are the top-level
      organizational
       unit and contain one or more workspaces.
  - name: AgentPoolService
    description: Manage shared agent pools and their lifecycle within a workspace.
  - name: AgentScheduleService
    description: >-
      Manage recurring schedules attached to agents. Schedules trigger
      objectives
       on a cadence defined by AgentScheduleSpec.Schedule.
  - name: AgentService
    description: >-
      Manage AI agents within a workspace. Agents define AI behavior and tool
      access.
  - name: AgentVariationService
    description: >-
      Manage variations of an agent and their tool, sub-agent, agent pool, and
      memory layer assignments.
  - name: MemoryService
    description: >-
      Manage memory layers and their entries. Layers are named containers that
      can
       be composed into an objective's memory cascade; entries are the keyed values
       within a layer. System-managed layers (e.g., episodic layers created by the
       runtime) cannot be mutated through this API.
  - name: ModelService
    description: |-
      Manage LLM models available to a workspace. Models represent provider and
       family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
       with the supported models and you can enable or disable each one. On
       customer-provided AI provider keys you can also override prices and, where
       the provider has no catalog, define models yourself.
  - name: ObjectiveEventStreamsService
  - name: ObjectiveService
  - name: ProfilesService
    description: |-
      Operations on profiles, the account-level principals (users, API keys,
       system) that authenticate against the API.
  - name: SearchService
  - name: TenantService
    description: >-
      Read and erase tenants and the subjects under them. Tenants and subjects
      are
       created by assertion — on objective creation or widget session mint — never
       directly, so this service has no create or update: it exists to enumerate what
       assertions have produced, and to destroy it on request.
  - name: ToolService
    description: >-
      Manage tool sets and the tools they contain. Tool sets group related
      tools,
       and tools define specific capabilities available to agents.

       When a tool set is managed, only API key actors can modify its tools; human
       (profile) actors cannot.
  - name: TrustedEndpointService
    description: |-
      Manage the account's trusted endpoints: the hosts its tool sets may send
       requests to. The list applies to every workspace in the account.
  - name: UploadService
    description: |-
      Issue short-lived presigned URLs for direct client-to-object-storage
       uploads. Created uploads can be referenced by id when creating or updating
       resources that accept binary content (e.g., MemoryEntry).
  - name: WidgetService
    description: |-
      Manage embeddable chat widgets. A widget binds an agent to a globally
       unique hostname with a per-widget origin allowlist; browsers reach it with
       session tokens minted via WidgetSessionService.
  - name: WidgetSessionService
    description: >-
      Mint and manage widget sessions. Session creation is server-to-server
      only:
       the customer's backend authenticates its visitor, asserts tenant/subject
       context, attaches any per-visitor secrets, and receives a short-lived
       bearer token the browser uses against the widget host.
  - name: WorkspaceAdminService
    description: >-
      Administer workspaces across the account: create and archive workspaces
      and
       manage their membership. These operations are account-scoped and require the
       admin role (a token whose profile holds the WorkOS admin role); they live
       under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces
       tree so an admin can manage any workspace in the account, including ones they
       are not themselves a member of.
  - name: WorkspaceSecretService
  - name: WorkspaceService
    description: |-
      Manage workspaces within an account. Workspaces provide organizational
       grouping and isolation for resources such as agents, tools, and API keys.

       This is the workspace-scoped, end-user surface. Administrative operations
       (create / archive workspaces, manage members) live in WorkspaceAdminService
       under /v1/account/workspaces and require the admin role.
paths:
  /v1/workspaces/{workspaceId}/agent_pools:
    post:
      tags:
        - AgentPoolService
        - Agent Pools
      summary: Create a new agent pool
      description: >-
        Creates an inactive agent pool and its membership atomically. All member
        agents must exist in the workspace. An empty description, empty
        membership, or duplicate member rejects the request.
      operationId: AgentPoolService_CreateAgentPool
      parameters:
        - name: workspaceId
          in: path
          description: Workspace ID.
          required: true
          schema:
            type: string
            example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentPoolRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPool'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      x-codeSamples:
        - lang: typescript
          label: TypeScript
          source: >-
            import Cadenya from '@cadenya/cadenya';


            const client = new Cadenya();

            const result = await client.agentPools.create({ metadata:
            {"name":"sample"}, spec:
            {"assignments":[{"agentId":"sample"}],"description":"sample"} });
        - lang: go
          label: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tcadenya \"go.cadenya.com/cadenya-go\"\n)\n\nfunc main() {\n\tclient, err := cadenya.NewClient()\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tctx := context.Background()\n\tparams := &cadenya.AgentPoolCreateParams{\n\t\tMetadata: &cadenya.CreateResourceMetadata{Name: \"sample\"},\n\t\tSpec: &cadenya.AgentPoolSpec{Description: \"sample\", Assignments: []cadenya.AgentPoolAssignment{cadenya.AgentPoolAssignment{AgentID: \"sample\"}}},\n\t}\n\tresult, err := client.AgentPools().Create(ctx, params)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Printf(\"%+v\\n\", result)\n}"
        - lang: python
          label: Python
          source: |-
            from cadenya import Cadenya

            with Cadenya() as client:
                result = client.agent_pools.create(metadata={"name": "sample"}, spec={"assignments": [{"agent_id": "sample"}], "description": "sample"})
                print(result)
        - lang: ruby
          label: Ruby
          source: >-
            require "cadenya"


            client = Cadenya::Client.new

            result = client.agent_pools.create(metadata: {"name" => "sample"},
            spec: {"assignments" => [{"agent_id" => "sample"}], "description" =>
            "sample"})

            puts result.inspect
        - lang: bash
          label: CLI
          source: |-
            cadenya agent-pools create \
              --name sample \
              --description sample \
              --assignment agent-id=sample
        - lang: shell
          label: curl
          source: |-
            curl --request POST \
              --url 'https://api.cadenya.com/v1/workspaces/workspace_123/agent_pools' \
              --header "Authorization: Bearer ${CADENYA_API_KEY}" \
              --header 'Content-Type: application/json' \
              --data '{"metadata":{"name":"sample"},"spec":{"assignments":[{"agentId":"sample"}],"description":"sample"}}'
components:
  schemas:
    CreateAgentPoolRequest:
      required:
        - metadata
        - spec
      type: object
      properties:
        workspaceId:
          readOnly: true
          example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
          type: string
          description: Workspace ID.
        metadata:
          $ref: '#/components/schemas/CreateResourceMetadata'
        spec:
          $ref: '#/components/schemas/AgentPoolSpec'
      description: >-
        Create a pool in INACTIVE state. Validate and persist membership
        atomically.
    AgentPool:
      required:
        - metadata
        - spec
        - state
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/ResourceMetadata'
        spec:
          $ref: '#/components/schemas/AgentPoolSpec'
        info:
          $ref: '#/components/schemas/AgentPoolInfo'
        state:
          readOnly: true
          enum:
            - AGENT_POOL_STATE_UNSPECIFIED
            - AGENT_POOL_STATE_ACTIVE
            - AGENT_POOL_STATE_INACTIVE
            - AGENT_POOL_STATE_ARCHIVED
          type: string
          description: |-
            Output only. Pools are created INACTIVE. Use :activate, :deactivate,
             :archive, and :unarchive to transition states. Unarchive returns INACTIVE.
          format: enum
      description: >-
        A workspace-scoped group of agents. When assigned to a variation, the
        pool
         exposes one callable target that routes a request to a member agent.
         Pool membership references agents; variation assignments reference the pool.
    Status:
      type: object
      properties:
        code:
          type: integer
          description: >-
            The status code, which should be an enum value of
            [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: >-
            A developer-facing error message, which should be in English. Any
            user-facing error message should be localized and sent in the
            [google.rpc.Status.details][google.rpc.Status.details] field, or
            localized by the client.
        details:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/WidgetSessionErrorInfo'
              - $ref: '#/components/schemas/GoogleProtobufAny'
          description: >-
            A list of messages that carry the error details.  There is a common
            set of message types for APIs to use.
      description: >-
        The `Status` type defines a logical error model that is suitable for
        different programming environments, including REST APIs and RPC APIs. It
        is used by [gRPC](https://github.com/grpc). Each `Status` message
        contains three pieces of data: error code, error message, and error
        details. You can find out more about this error model and how to work
        with it in the [API Design
        Guide](https://cloud.google.com/apis/design/errors).
    CreateResourceMetadata:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          description: >-
            Human-readable name for the resource (e.g., "Customer Support
            Agent", "Email Tool")
        externalId:
          type: string
          description: >-
            External ID for the resource (e.g., a workflow ID from an external
            system)
        labels:
          type: object
          additionalProperties:
            type: string
          description: |-
            Key-value pairs for categorization and filtering. Values are 0-63
             alphanumeric characters with "-", "_", or "." allowed between; keys
             follow the same shape and additionally accept an optional DNS-subdomain
             prefix (e.g. "cadenya.com/") of at most 253 characters.
             Examples: {"environment": "production", "team": "platform", "version": "v2"}
      description: |-
        CreateResourceMetadata contains the user-provided fields for creating
         a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id,
         created_at) are excluded since they are set by the server.
    AgentPoolSpec:
      required:
        - description
        - assignments
      type: object
      properties:
        description:
          minLength: 1
          type: string
          description: Describes when a calling agent should use this pool.
        state:
          type: object
          additionalProperties: true
          description: >-
            JSON Schema defining the input arguments for this pool's callable
            tool.
             When the pool is assigned to an agent variation, this schema tells the LLM
             what arguments to supply. The supplied arguments provide the context used
             to route the request to an agent in the pool.
        assignments:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/AgentPoolAssignment'
          description: >-
            Complete set of member agents, all in the pool's workspace. At least
            one
             member is required. Order has no meaning; duplicate agent IDs are invalid.
        instructions:
          type: string
          description: |-
            Instructions for routing requests to an agent in the pool.
             If empty, defaults to "Which agent is best suited to handle this request?".
      description: >-
        AgentPoolSpec describes the pool's purpose, membership, input schema,
        and routing instructions.
    ResourceMetadata:
      required:
        - id
        - accountId
        - workspaceId
        - name
        - profileId
        - createdAt
        - externalId
        - labels
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: >-
            Unique identifier for the resource (prefixed ULID, e.g.,
            "agent_01HXK...")
        accountId:
          readOnly: true
          example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
          type: string
          description: >-
            Account this resource belongs to for multi-tenant isolation
            (prefixed ULID)
        workspaceId:
          readOnly: true
          example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
          type: string
          description: >-
            Workspace this resource belongs to for organizational grouping
            (prefixed ULID)
        name:
          type: string
          description: >-
            Human-readable name for the resource (e.g., "Customer Support
            Agent", "Email Tool")
             Required for resources that users interact with directly
        externalId:
          type: string
          description: >-
            External ID for the resource (e.g., a workflow ID from an external
            system)
        labels:
          type: object
          additionalProperties:
            type: string
          description: |-
            Key-value pairs for categorization and filtering. Values are 0-63
             alphanumeric characters with "-", "_", or "." allowed between; keys
             follow the same shape and additionally accept an optional DNS-subdomain
             prefix (e.g. "cadenya.com/") of at most 253 characters.
             Examples: {"environment": "production", "team": "platform", "version": "v2"}
        profileId:
          readOnly: true
          example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
          type: string
          description: ID of the actor (user or service account) that created this resource
        createdAt:
          readOnly: true
          type: string
          description: Timestamp when this resource was created
          format: date-time
        updatedAt:
          readOnly: true
          type: string
          description: Timestamp when this resource was last updated
          format: date-time
      description: >-
        Standard metadata for persistent, named resources (e.g., agents, tools,
        prompts)
    AgentPoolInfo:
      required:
        - assignedAgents
        - createdBy
      type: object
      properties:
        assignedAgents:
          readOnly: true
          type: integer
          description: Number of member agents in spec.assignments.
          format: int32
        createdBy:
          $ref: '#/components/schemas/Profile'
      description: AgentPoolInfo represents the information of an agent pool.
    WidgetSessionErrorInfo:
      type: object
      description: >-
        google.rpc.ErrorInfo detail for widget lifecycle failures. Match both
        domain and reason; ignore unknown reasons rather than renewing
        automatically.
      required:
        - '@type'
        - domain
        - reason
      properties:
        '@type':
          type: string
          enum:
            - type.googleapis.com/google.rpc.ErrorInfo
        domain:
          type: string
          enum:
            - api.cadenya.com
        reason:
          $ref: '#/components/schemas/WidgetSessionErrorReason'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Optional non-sensitive context. Never contains tokens or secrets.
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: >-
        Contains an arbitrary serialized message along with a @type that
        describes the type of the serialized message.
    AgentPoolAssignment:
      required:
        - agentId
      type: object
      properties:
        agentId:
          example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y
          minLength: 1
          type: string
          description: Canonical ID of an agent in the pool's workspace.
      description: |-
        A member of a pool, identified by its agent ID. This is distinct from a
         VariationAssignment, which attaches the entire pool to a variation.
    Profile:
      required:
        - metadata
        - spec
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/AccountResourceMetadata'
        spec:
          $ref: '#/components/schemas/ProfileSpec'
      description: |-
        A profile identifies a user or non-human principal (such as an API key)
         at the account level. Profiles are account-scoped and can be granted access
         to multiple workspaces.
    WidgetSessionErrorReason:
      type: string
      description: >-
        TOKEN_EXPIRED identifies access-token expiry beyond the 60-second
        clock-skew tolerance. That token cannot renew; use already-installed
        newer credentials or require explicit app reauthentication. SESSION_*
        reasons are terminal. Never infer renewability from HTTP status alone.
      enum:
        - TOKEN_EXPIRED
        - SESSION_REVOKED
        - SESSION_EXPIRED
        - SESSION_EXHAUSTED
    AccountResourceMetadata:
      required:
        - id
        - accountId
        - name
        - profileId
        - externalId
        - labels
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: >-
            Unique identifier for the resource (prefixed ULID, e.g.,
            "apikey_01HXK...")
        accountId:
          readOnly: true
          example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
          type: string
          description: >-
            Account this resource belongs to for multi-tenant isolation
            (prefixed ULID)
        name:
          type: string
          description: >-
            Human-readable name for the resource (e.g., "Customer Support
            Agent", "Email Tool")
             Required for resources that users interact with directly
        externalId:
          type: string
          description: >-
            External ID for the resource (e.g., a workflow ID from an external
            system)
        labels:
          type: object
          additionalProperties:
            type: string
          description: |-
            Key-value pairs for categorization and filtering. Values are 0-63
             alphanumeric characters with "-", "_", or "." allowed between; keys
             follow the same shape and additionally accept an optional DNS-subdomain
             prefix (e.g. "cadenya.com/") of at most 253 characters.
             Examples: {"environment": "production", "team": "platform", "version": "v2"}
        profileId:
          readOnly: true
          example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
          type: string
        createdAt:
          readOnly: true
          type: string
          format: date-time
      description: >-
        AccountResourceMetadata is used to represent a resource that is
        associated to an account but not to a workspace.
    ProfileSpec:
      required:
        - type
        - email
        - name
      type: object
      properties:
        email:
          type: string
          description: >-
            Email address of the profile. Required and unique within an account
            for
             user profiles.
        name:
          type: string
          description: Display name (e.g., "Bobby Tables").
        type:
          enum:
            - PROFILE_TYPE_UNSPECIFIED
            - PROFILE_TYPE_USER
            - PROFILE_TYPE_API_KEY
            - PROFILE_TYPE_SYSTEM
          type: string
          description: >-
            Whether this profile represents a human user, an API key, or a
            system
             principal.
          format: enum
      description: Configuration for a profile.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.