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

# Open a session

> Open an isolated checkout of a workspace's monorepo to create apps and edit files.

A **build session** is an isolated checkout of a workspace's monorepo — the same concept as the Zite MCP
[sandbox](/mcp/build-loop#sandboxes). You create apps and edit files inside a session, then
[commit](/build-api/sessions/commit) to build and version your changes.

The response includes the workspace's file tree, its apps, and the **framework guide** — the same spec
agents receive, describing the [project layout](/framework/project-structure) and conventions.

* Every file and commit call takes the `sessionId` returned here.
* Use **one session per concurrent build** so parallel jobs don't clobber each other.
* Sessions auto-stop after \~15 minutes idle and re-boot transparently on the next call.


## OpenAPI

````yaml build-api/openapi.json POST /workspaces/{workspaceId}/sessions
openapi: 3.0.1
info:
  title: Zite Build API
  description: >-
    Create, build, and deploy Zite apps programmatically — the REST equivalent
    of the Zite MCP build tools. Use it from a script, a CI pipeline, or your
    own agent.


    ## Authentication


    All requests require a Bearer API key from your Developer settings:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```

    The key acts as you — it can only see and change workspaces you have access
    to, and every change is attributed to you.


    ## Base URL


    https://api.zite.com/v1


    ## Errors


    Errors return `{ "statusCode": 404, "error": "Not Found", "message":
    "Workspace not found" }`. Notable statuses: `401` (bad or missing key),
    `402` (the build tools aren't in your plan), `404`, `409` (a commit push
    conflict — pull, rebase, and commit again), and `400` for validation
    failures and publishing before a build is green.
  version: 1.0.0
servers:
  - url: https://api.zite.com/v1
    description: Zite Build API
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: Create workspaces and inspect the apps in them.
  - name: Build sessions
    description: >-
      Open an isolated checkout of a workspace, create apps, edit files, check,
      and commit.
  - name: Deployments
    description: Publish built apps, manage versions, roll back, and read runtime logs.
paths:
  /workspaces/{workspaceId}/sessions:
    post:
      tags:
        - Build sessions
      summary: Open a session
      description: >-
        Opens an isolated checkout of the workspace's monorepo. The response
        includes the workspace's file tree, its apps, and the framework guide —
        the same spec agents receive. Every file and commit call takes the
        returned `sessionId`. Sessions auto-stop after ~15 minutes idle and
        re-boot transparently on the next call.
      operationId: openSession
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '201':
          description: The open session
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    description: >-
                      Pass this in the path of every session call. Opaque;
                      encodes the workspace and an isolated checkout.
                    example: >-
                      sbx:wsp8bce4d1edc51710:2f0c9a1e-77f4-4b3e-9f2a-1c7b40e8d316
                  workspaceId:
                    type: string
                    example: wsp8bce4d1edc51710
                  apps:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppSummary'
                  files:
                    type: array
                    description: The workspace file tree, relative to the workspace root.
                    items:
                      type: string
                  integrations:
                    type: array
                    description: Integrations already connected to the workspace.
                    items:
                      type: object
                  docs:
                    type: array
                    description: Index of fetchable framework guides and recipes.
                    items:
                      type: object
                  guide:
                    type: string
                    description: >-
                      The zitejs framework guide. Read it before writing app
                      code.
              example:
                sessionId: ses_9f2a1c7b40e8
                apps:
                  - id: app_a1b2c3
                    name: Agent console
                    dir: apps/agent-console
                files:
                  - apps/agent-console/src/App.tsx
                  - ...
                guide: |-
                  # Building Zite apps — framework guide
                  ...
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      description: The workspace ID.
      schema:
        type: string
      example: wsp_8bce4d1edc51710
  schemas:
    AppSummary:
      type: object
      properties:
        id:
          type: string
          example: app_a1b2c3
        name:
          type: string
          example: Agent console
        type:
          type: string
          description: '`zite` for apps; forms keep their form type.'
          example: zite
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: string
          example: Not Found
        message:
          type: string
          example: Workspace not found
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Missing or invalid API key.
    NotFound:
      description: The resource does not exist or your key cannot access it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Workspace not found.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Enter your Zite API key. Format: Bearer <api_key>'

````