> ## 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, so 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 active: the free trial has ended, or the plan
    doesn't include them), `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>'

````

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