Launch coding session

Changed on

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

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.

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

Path parameters

app_idstring required

Headers

Idempotency-Keystring required

A unique key for this task. Reuse it with the same runtime inputs on retries; you may omit the previously associated client_reference.

Example:flag-cleanup-123

Request body

promptstring required

The coding task to carry out. The agent opens a pull request when the task asks for a change.

titlestring required

A short name for the session.

existing_branchstring nullable

An existing repository branch to work on, or null to create an isolated branch.

source_refstring nullable

The Git ref a new branch starts from, or null for the imported base branch.

pull_request_bodystring nullable

Additional Markdown to include in the pull request description, or null.

commit_messagestring nullable

An optional message for this session's commits, including any required trailers, or null for a generated message.

file_urlsstring[] nullable

Images for the agent to see alongside the text: URLs of files uploaded to this app, or null.

client_referencestring nullable

An opaque reference used by your application to reconcile sessions, or null.

expected_repository_full_namestring 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.

Example request

{
  "prompt": "Remove the retired example-feature flag, preserving its enabled behavior.",
  "title": "Remove example-feature",
  "existing_branch": "feature/review-fixes",
  "source_ref": "main",
  "pull_request_body": "Requested by the release workflow.",
  "commit_message": "fix: remove the retired flag",
  "client_reference": "release-task-123",
  "expected_repository_full_name": "acme/project"
}

Response

Successful Response

launch_keystring 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_referencestring nullable

Your application reconciliation reference, or null.

idstring 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_idstring 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_idstring 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_namestring required

The connected repository the session runs in.

branch_idstring nullable required

The session's Base Code branch identifier, or null before provisioning.

branch_namestring nullable required

The session's working Git branch, or null before provisioning.

session_urlstring nullable required

The Base Code editor URL for inspecting the session or answering pending questions, or null until its branch is provisioned.

error_codestring 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.

summarystring 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_changesboolean

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.

Example response

{
  "launch_key": "flag-cleanup-123",
  "client_reference": "release-task-123",
  "id": "6820f3a4e7b91d003c45a1f2",
  "state": "running",
  "message_id": "ca00e880-1111-4444-aaaa-ccddeeff0011",
  "input_request_id": "ca00e880-1111-4444-aaaa-ccddeeff0011",
  "repository_full_name": "acme/project",
  "branch_id": "6820f3a4e7b91d003c45a1f3",
  "branch_name": "base-code/fix-login-redirect-45a1f2",
  "session_url": "https://app.base44.com/apps/6820f3a4e7b91d003c45a1f2/editor/preview",
  "pull_request": {
    "number": 123,
    "url": "https://github.com/acme/project/pull/123"
  },
  "error_code": "execution_failed",
  "outcome": "pull_request",
  "summary": "Removed the retired flag and kept the enabled behavior."
}

Changes

  • 0cf0a6b20badRevision changes
    • info

      added the new optional request property

  • be100564f5a1Revision changes
    • info

      the request property's maxLength was increased from 99611 to 99618

    • info

      added the optional property to the response with the status