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

# Fork a session

> Create an independent session from a fresh workspace snapshot, or the latest saved snapshot when stopped, without replaying messages or adding context. The fork returns right away and its messages queue until its workspace finishes booting.



## OpenAPI

````yaml https://api.tembo.io/public-api/openapi/public post /v1/sessions/{sessionId}/fork
openapi: 3.1.0
info:
  title: Tembo Public API
  description: >-
    Manage agents, sessions, repositories, and organization resources with the
    Tembo API.
  version: 1.0.0
servers:
  - url: https://api.tembo.io
    description: Tembo API
  - url: https://{deployment-origin}/api/public-api
    description: Self-hosted Tembo
    variables:
      deployment-origin:
        default: tembo.example.com
        description: Hostname of your self-hosted Tembo deployment
security: []
paths:
  /v1/sessions/{sessionId}/fork:
    post:
      tags:
        - Sessions
      summary: Fork a session
      description: >-
        Create an independent session from a fresh workspace snapshot, or the
        latest saved snapshot when stopped, without replaying messages or adding
        context. The fork returns right away and its messages queue until its
        workspace finishes booting.
      operationId: forkSession
      parameters:
        - in: path
          name: sessionId
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  description: >-
                    Optional first task for the independent fork. Existing
                    messages are not replayed.
                  type: string
                  minLength: 1
                  maxLength: 1000000
                title:
                  description: Display title for the forked session.
                  type: string
                  minLength: 1
                  maxLength: 1000
                queueRightAway:
                  default: true
                  description: >-
                    Start the supplied prompt immediately. Without a prompt, the
                    fork waits for a new message.
                  type: boolean
              additionalProperties: false
      responses:
        '201':
          description: Fork a session
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    type:
                      - string
                      - 'null'
                  agentId:
                    anyOf:
                      - type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      - type: 'null'
                  artifactType:
                    anyOf:
                      - type: string
                        enum:
                          - PullRequest
                          - ToolCall
                          - Plan
                          - Response
                          - File
                          - Service
                          - Source
                      - type: 'null'
                  baseBranch:
                    type:
                      - string
                      - 'null'
                  branchName:
                    type:
                      - string
                      - 'null'
                  createdAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  externalId:
                    type:
                      - string
                      - 'null'
                  externalUrl:
                    type:
                      - string
                      - 'null'
                  id:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  kind:
                    type: string
                  lastQueuedAt:
                    anyOf:
                      - type: string
                        format: date-time
                        pattern: >-
                          ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                      - type: 'null'
                  lastSeenAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  level:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  mode:
                    default: normal
                    type: string
                    enum:
                      - normal
                      - planning
                  parentSessionId:
                    anyOf:
                      - type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      - type: 'null'
                    description: The session whose agent created this session.
                  projectId:
                    type:
                      - string
                      - 'null'
                  sandboxSize:
                    anyOf:
                      - type: string
                        enum:
                          - nano
                          - micro
                          - small
                          - medium
                          - large
                          - xl
                          - xxl
                          - ultra
                      - type: 'null'
                  sessionType:
                    default: Chat
                    type: string
                    enum:
                      - Chat
                      - Terminal
                  targetBranch:
                    type:
                      - string
                      - 'null'
                  title:
                    type: string
                  updatedAt:
                    type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                  visibility:
                    type: string
                    enum:
                      - private
                      - public
                    description: >-
                      Deprecated: `private` when shared with no one, `public`
                      when shared with anyone. List the session’s shares for its
                      exact audiences.
                    deprecated: true
                  artifacts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        type:
                          type: string
                          enum:
                            - PullRequest
                            - ToolCall
                            - Plan
                            - Response
                            - File
                            - Service
                            - Source
                        createdAt:
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                        updatedAt:
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                        pullRequests:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              url:
                                type: string
                                format: uri
                              title:
                                type:
                                  - string
                                  - 'null'
                              status:
                                type: string
                                enum:
                                  - open
                                  - merged
                                  - closed
                              isDraft:
                                type: boolean
                              sourceBranch:
                                type:
                                  - string
                                  - 'null'
                              createdAt:
                                type: string
                                format: date-time
                                pattern: >-
                                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                              agent:
                                type:
                                  - string
                                  - 'null'
                              diff:
                                anyOf:
                                  - type: object
                                    properties:
                                      additions:
                                        type: integer
                                        minimum: 0
                                        maximum: 9007199254740991
                                      deletions:
                                        type: integer
                                        minimum: 0
                                        maximum: 9007199254740991
                                      data:
                                        type: string
                                        maxLength: 1000000
                                    additionalProperties: false
                                  - type: 'null'
                              updatedAt:
                                type: string
                                format: date-time
                                pattern: >-
                                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
                              baseBranch:
                                anyOf:
                                  - type: string
                                    maxLength: 500
                                  - type: 'null'
                              headSha:
                                anyOf:
                                  - type: string
                                    maxLength: 200
                                  - type: 'null'
                              author:
                                anyOf:
                                  - type: object
                                    properties:
                                      avatarUrl:
                                        anyOf:
                                          - type: string
                                            format: uri
                                          - type: 'null'
                                      login:
                                        anyOf:
                                          - type: string
                                            maxLength: 500
                                          - type: 'null'
                                    required:
                                      - avatarUrl
                                      - login
                                    additionalProperties: false
                                  - type: 'null'
                              codeRepository:
                                anyOf:
                                  - type: object
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                        pattern: >-
                                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      name:
                                        type: string
                                      owner:
                                        type:
                                          - string
                                          - 'null'
                                      baseBranch:
                                        type:
                                          - string
                                          - 'null'
                                      provider:
                                        type: string
                                    required:
                                      - id
                                      - name
                                      - owner
                                      - baseBranch
                                      - provider
                                    additionalProperties: false
                                  - type: 'null'
                            required:
                              - id
                              - url
                              - title
                              - status
                              - isDraft
                              - sourceBranch
                              - createdAt
                              - agent
                              - diff
                              - updatedAt
                              - baseBranch
                              - headSha
                              - author
                              - codeRepository
                            additionalProperties: false
                      required:
                        - id
                        - type
                        - createdAt
                        - updatedAt
                        - pullRequests
                      additionalProperties: false
                  automaticSizing:
                    type: boolean
                    description: Whether the session VM is sized automatically.
                  description:
                    type:
                      - string
                      - 'null'
                  diffSummary:
                    anyOf:
                      - type: object
                        properties:
                          additions:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          deletions:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                        required:
                          - additions
                          - deletions
                        additionalProperties: false
                      - type: 'null'
                  folderId:
                    anyOf:
                      - type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      - type: 'null'
                    description: >-
                      Sidebar folder the authenticated user filed this session
                      in.
                  htmlUrl:
                    type: string
                    format: uri
                  isPinned:
                    type: boolean
                  project:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                            pattern: >-
                              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          name:
                            type: string
                          icon:
                            type: string
                            enum:
                              - folder
                              - code
                              - terminal
                              - book
                              - brain
                              - bug
                              - building
                              - cloud
                              - globe
                              - idea
                              - tools
                              - magic
                              - processor
                              - sandbox
                              - server
                              - tasks
                              - tactics
                              - images
                              - database
                              - api
                              - mobile
                              - package
                          color:
                            type: string
                            enum:
                              - neutral
                              - red
                              - orange
                              - yellow
                              - green
                              - teal
                              - blue
                              - purple
                              - pink
                        required:
                          - id
                          - name
                          - icon
                          - color
                        additionalProperties: false
                      - type: 'null'
                  sessionSource:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        pattern: >-
                          ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      name:
                        type: string
                      type:
                        type: string
                      repositories:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              pattern: >-
                                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            name:
                              type: string
                            provider:
                              type: string
                          required:
                            - id
                            - name
                            - provider
                          additionalProperties: false
                    required:
                      - id
                      - name
                      - type
                      - repositories
                    additionalProperties: false
                  sourcePullRequest:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                            pattern: >-
                              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          url:
                            type: string
                            format: uri
                          title:
                            type:
                              - string
                              - 'null'
                          status:
                            type: string
                            enum:
                              - open
                              - merged
                              - closed
                          isDraft:
                            type: boolean
                        required:
                          - id
                          - url
                          - title
                          - status
                          - isDraft
                        additionalProperties: false
                      - type: 'null'
                  state:
                    type: object
                    properties:
                      current:
                        type: string
                        enum:
                          - inProgress
                          - queued
                          - completed
                          - failed
                          - cancelled
                      isQueued:
                        type: boolean
                      isCancelled:
                        type: boolean
                      isCompleted:
                        type: boolean
                      isFailed:
                        type: boolean
                      inProgress:
                        type: boolean
                    required:
                      - isQueued
                      - isCancelled
                      - isCompleted
                      - isFailed
                      - inProgress
                    additionalProperties: false
                required:
                  - agent
                  - agentId
                  - artifactType
                  - baseBranch
                  - branchName
                  - createdAt
                  - externalId
                  - externalUrl
                  - id
                  - kind
                  - lastQueuedAt
                  - lastSeenAt
                  - level
                  - mode
                  - parentSessionId
                  - projectId
                  - sandboxSize
                  - sessionType
                  - targetBranch
                  - title
                  - updatedAt
                  - visibility
                  - artifacts
                  - automaticSizing
                  - description
                  - diffSummary
                  - folderId
                  - htmlUrl
                  - isPinned
                  - project
                  - sessionSource
                  - sourcePullRequest
                  - state
                additionalProperties: false
        '400':
          description: >-
            Invalid request or missing required organization or user
            information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '401':
          description: The session is private
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '403':
          description: The caller is not permitted to perform this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '404':
          description: Session resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '409':
          description: Session operation conflicts with existing data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '500':
          description: Session operation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '502':
          description: Session runtime or provider operation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
      security:
        - apiKey: []
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK
          source: >
            import Tembo from '@tembo-io/sdk';


            const client = new Tembo();


            const session = await
            client.sessions.fork('7c9e6679-7425-40de-944b-e07fc1f90ae7');
        - lang: rust
          label: Rust SDK
          source: |
            use tembo_rs::*;

            let client = Tembo::from_env()?;

            let response = client
                .sessions()
                .fork("7c9e6679-7425-40de-944b-e07fc1f90ae7")
                .send()
                .await?;
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````

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