--- title: "Launch coding session" method: POST path: "/api/apps/{app_id}/imported/sessions" --- # Launch coding session `POST /api/apps/{app_id}/imported/sessions` ## Request - Base URL: `https://app.base44.com` - URL: `https://app.base44.com/api/apps/{app_id}/imported/sessions` - Auth: HTTP bearer This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production. Start a coding task in an isolated branch or on an existing working branch of an imported repository. Authenticate with a platform Bearer token whose user has write access to the app and repository. The request returns before the coding task runs and consumes credits through the regular Builder path. Poll the returned session ID for progress and its pull request. Reuse the Idempotency-Key and runtime inputs on retries. You may omit the previously associated client_reference; changing a supplied reference or any runtime input with the same key returns idempotency_conflict. Launch and cancellation share a limit of 6 requests per minute per user. Every response has X-Request-Id and rate-limit headers; 429 responses include Retry-After. Sessions that need an approval or clarification report needs_input; use session_url to continue in Base Code. This endpoint doesn't merge pull requests. ## Path parameters - `app_id` string, required ## Headers - `Idempotency-Key` string, required: A unique key for this task. Reuse it with the same runtime inputs on retries; you may omit the previously associated client_reference. ## Request body - LaunchSession - `prompt` string, required: The coding task to carry out. The agent opens a pull request when the task asks for a change. - `title` string, required: A short name for the session. - `existing_branch` string, nullable: An existing repository branch to work on, or `null` to create an isolated branch. - `source_ref` string, nullable: The Git ref a new branch starts from, or `null` for the imported base branch. - `pull_request_body` string, nullable: Additional Markdown to include in the pull request description, or `null`. - `commit_message` string, nullable: An optional message for this session's commits, including any required trailers, or `null` for a generated message. - `file_urls` string[], nullable: Images for the agent to see alongside the text: URLs of files uploaded to this app, or `null`. - `client_reference` string, nullable: An opaque reference used by your application to reconcile sessions, or null. - `expected_repository_full_name` string, nullable: The repository you expect this app to be connected to, or `null` to use its current connection. A mismatch refuses the launch before starting work. ## Response `202` Successful Response - SessionResponse - `launch_key` string, nullable: The original Idempotency-Key, or `null` for sessions created before key recovery was recorded. Use the same principal and key to retry a queued launch. - `client_reference` string, nullable: Your application reconciliation reference, or null. - `id` string, required: The session's opaque identifier. - `state` 'queued' | 'running' | 'opening_pull_request' | 'needs_input' | 'completed' | 'failed' | 'cancelling' | 'cancelled', required: The session's state: `queued`, `running`, `opening_pull_request`, `needs_input`, `completed`, `failed`, `cancelling`, or `cancelled`. - `message_id` string, nullable, required: The UUID of the session's user message, or `null` before dispatch. Queued processing updates it to the UUID used for the turn. - `input_request_id` string, nullable: Opaque identifier of the current question or approval pause, or `null` when the session is not waiting for input or the pause predates identifier tracking. Use it to deduplicate notifications for repeated input requests. To answer, use the `input_request_id` from Get a coding session's open question. - `repository_full_name` string, required: The connected repository the session runs in. - `branch_id` string, nullable, required: The session's Base Code branch identifier, or `null` before provisioning. - `branch_name` string, nullable, required: The session's working Git branch, or `null` before provisioning. - `session_url` string, nullable, required: The Base Code editor URL for inspecting the session or answering pending questions, or `null` until its branch is provisioned. - `pull_request` SessionPullRequest, required - `number` integer, required: The pull request's number in the connected repository. - `url` string, required: The pull request's URL. - `error_code` string, nullable, required: The stable failure cause, or `null` if there is no failure. - `outcome` 'pull_request' | 'answer', nullable: How a `completed` session ended: `pull_request` when it opened or updated a pull request, `answer` when it ended without one and replied instead; `has_unpublished_changes` says whether that branch still changes files. `null` until the session completes. - `summary` string, nullable: The session's final reply in Markdown, up to 10,000 characters: the answer for an `answer` outcome, the change summary for a `pull_request` outcome. `null` until the session publishes. - `has_unpublished_changes` boolean: `true` when an `answer` session's branch changes files that no pull request carries yet: send a message asking for one to have the agent open it. `false` otherwise. ## Other responses - `401`: `unauthenticated`: Missing or invalid credentials. - `403`: `forbidden`: You don't have write access to this app or repository. `publisher_access_denied`: The configured GitHub App publisher is not granted to this workspace and repository. - `404`: `not_found`: The imported app or session was not found. - `409`: `idempotency_conflict`: The key was used with different inputs. `repository_changed`: The imported repository doesn't match this task. `conflict`: The repository isn't connected to GitHub in the app's current workspace; reconnect it, then retry. `publisher_unavailable`: The GitHub App publisher has no active installation for this repository, or it is suspended. `publisher_permission_missing`: The publisher lacks pull-request write permission. - `422`: `invalid_request`: The input or Idempotency-Key is invalid. - `429`: `rate_limited`: Retry after the number of seconds in Retry-After. - `502`: `publisher_unavailable`: The GitHub App publisher could not authenticate with GitHub (installation token or signing key). Not retryable until an administrator fixes it. - `503`: `authority_unavailable`: GitHub could not confirm repository access. Retry the launch with the same Idempotency-Key. ## Changes > 58 revisions in range; 1 not diffed. - **2026-10-18** `0cf0a6b20bad`: 1 info - added the new optional request property `file_urls` - **2026-10-15** `be100564f5a1`: 2 info - the `prompt` request property's maxLength was increased from `99611` to `99618` - added the optional property `has_unpublished_changes` to the response with the `202` status - **2026-10-15** `99162eae7daf`: 1 info - removed the non-success response with the status `500` - **2026-10-14** `31b59ecae1c9`: 2 info - added the optional property `outcome` to the response with the `202` status - added the optional property `summary` to the response with the `202` status - **2026-10-13** `b92cc2f13639`: 1 info - endpoint added [Operation history](https://skmtc.dev/adexad/apis/base44-app-management-api/changes/api/apps/:app_id/imported/sessions/post.md) --- [API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adexad/apis/base44-app-management-api/revisions/fa29e915c226?raw)