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

# Agent Ensure Workspace

> Plan #1: lazy workspace provisioning.

Called by the agent's can_use_tool_callback the first time a
write-tool fires in a turn (Edit, Write, MultiEdit, Bash, Read on a
/data/user-addons/ path). Triggers branch resolution + pod-side
git clone, marks the task as provisioned, returns the resolved
branch info.

Idempotent: subsequent calls for the same task return the cached
result (warm=True) without re-resolving or re-cloning. The
per-task asyncio.Lock serializes concurrent calls from one agent.

Auth: shared pod token, same pattern as /api/agent/pr/create.



## OpenAPI

````yaml /openapi.json post /api/agent/workspace/ensure
openapi: 3.1.0
info:
  description: >-
    Public CodeCobra API. Authenticate by sending a personal API key in the
    `Authorization: Bearer <key>` header. Generate keys from Settings → API keys
    in the CodeCobra dashboard.
  title: CodeCobra Public API
  version: 1.0.0
servers: []
security: []
paths:
  /api/agent/workspace/ensure:
    post:
      tags:
        - public
      summary: Agent Ensure Workspace
      description: |-
        Plan #1: lazy workspace provisioning.

        Called by the agent's can_use_tool_callback the first time a
        write-tool fires in a turn (Edit, Write, MultiEdit, Bash, Read on a
        /data/user-addons/ path). Triggers branch resolution + pod-side
        git clone, marks the task as provisioned, returns the resolved
        branch info.

        Idempotent: subsequent calls for the same task return the cached
        result (warm=True) without re-resolving or re-cloning. The
        per-task asyncio.Lock serializes concurrent calls from one agent.

        Auth: shared pod token, same pattern as /api/agent/pr/create.
      operationId: agent_ensure_workspace_api_agent_workspace_ensure_post
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentWorkspaceEnsureResponse'
          description: Successful Response
components:
  schemas:
    AgentWorkspaceEnsureResponse:
      description: 'Plan #1: response from /api/agent/workspace/ensure.'
      properties:
        github_branch:
          anyOf:
            - type: string
            - type: 'null'
          title: Github Branch
        selected_branches:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Selected Branches
        status:
          title: Status
          type: string
        warm:
          default: false
          title: Warm
          type: boolean
      required:
        - status
      title: AgentWorkspaceEnsureResponse
      type: object

````