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

# Link an Environment

> PUT /agents/{agentName}/parent links an agent as an environment of a project, and also renames an environment or moves it.



## OpenAPI

````yaml PUT /agents/{agentName}/parent
openapi: 3.0.0
info:
  title: Pipecat Cloud
  version: 1.0.0
  description: >-
    REST API for Pipecat Cloud. The public API (`/v1/public`, authenticated with
    a public API key) starts agent sessions and proxies requests to them. The
    private API (`/v1`, authenticated with a private API key) manages agents,
    secrets, builds, regions, and organization settings.
servers:
  - url: https://api.pipecat.daily.co/v1
    description: Private API server
security: []
paths:
  /agents/{agentName}/parent:
    put:
      summary: Link an environment to a project
      description: >-
        Links `agentName` as an environment of `parent`. An environment is an
        agent of its own, with its own repository binding, secrets and scaling;
        the link only records that it belongs to the project.


        This sets the whole link, so it also renames an environment or moves it
        to another project, and every rule is checked again either way.


        The link is refused when the two agents are in different regions, when
        either side already has environments (environments do not nest), when
        the project has PR previews on, when the name is already taken by
        another of the project's environments, or when `agentName` is a PR
        preview, whose link belongs to its pull request.
      operationId: linkEnvironment
      parameters:
        - name: agentName
          in: path
          required: true
          description: Name of the agent to link as an environment
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - parent
                - environmentName
              properties:
                parent:
                  type: string
                  description: Name of the project the environment belongs to
                environmentName:
                  type: string
                  maxLength: 50
                  description: >-
                    Its name among the project's environments: two to 50
                    lowercase letters, digits and dashes, starting and ending
                    with a letter or digit. `production` is the project itself,
                    and the `pr-` prefix is reserved for PR previews.
            example:
              parent: my-bot
              environmentName: staging
      responses:
        '200':
          description: The stored link
          content:
            application/json:
              schema:
                type: object
                properties:
                  serviceName:
                    type: string
                    description: The agent that was linked
                  parent:
                    type: string
                    nullable: true
                    description: The project it belongs to, or null when unlinked
                  environmentName:
                    type: string
                    nullable: true
                    description: >-
                      Its name among the project's environments, or null when
                      unlinked
              example:
                serviceName: my-bot-staging
                parent: my-bot
                environmentName: staging
        '400':
          description: >-
            A reserved or malformed environment name, a region mismatch, or an
            agent asked to be an environment of itself
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: An agent cannot be an environment of itself
                code: '400'
        '404':
          description: The agent or the parent was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Parent agent 'my-bot' not found
                code: '404'
        '409':
          description: >-
            Environments would nest, the name is taken, the project has PR
            previews on, or the agent is a PR preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Agent 'my-bot' already has an environment 'staging'
                  ('my-bot-stg').
                code: '409'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
                code: '500'
      security:
        - PrivateKeyAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        code:
          type: string
          description: >-
            Error code for programmatic handling. For general errors it is the
            HTTP status as a string, such as `"404"`. Deployment-related codes
            (PCC-*) are documented at
            https://docs.pipecat.ai/pipecat-cloud/fundamentals/error-codes
      required:
        - error
        - code
  securitySchemes:
    PrivateKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Authentication requires a Pipecat Cloud Private API token.


        Generate a Private API key from your Dashboard (Settings > API Keys >
        Private > Create key) and include it as a Bearer token in the
        Authorization header.

````

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