> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.
# Launch coding session
> 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.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/imported/sessions
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/apps/{app_id}/imported/sessions:
post:
summary: Launch coding session
description: >-
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.
operationId: launch_session_api_apps__app_id__imported_sessions_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
title: App Id
- name: Idempotency-Key
in: header
required: true
schema:
type: string
minLength: 1
maxLength: 200
pattern: ^[A-Za-z0-9_.:-]+$
description: >-
A unique key for this task. Reuse it with the same runtime inputs
on retries; you may omit the previously associated
client_reference.
examples:
- flag-cleanup-123
title: Idempotency-Key
description: >-
A unique key for this task. Reuse it with the same runtime inputs on
retries; you may omit the previously associated client_reference.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LaunchSession'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionResponse'
'401':
description: '`unauthenticated`: Missing or invalid credentials.'
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'403':
description: >-
`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.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'404':
description: '`not_found`: The imported app or session was not found.'
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'409':
description: >-
`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.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'422':
description: '`invalid_request`: The input or Idempotency-Key is invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'429':
description: '`rate_limited`: Retry after the number of seconds in Retry-After.'
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'500':
description: >-
`internal_error`: Unexpected failure. Retry a launch with the same
Idempotency-Key.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'502':
description: >-
`publisher_unavailable`: The GitHub App publisher could not
authenticate with GitHub (installation token or signing key). Not
retryable until an administrator fixes it.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
'503':
description: >-
`authority_unavailable`: GitHub could not confirm repository access.
Retry the launch with the same Idempotency-Key.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorEnvelope'
security:
- PersonalAccessTokenAuth:
- full_access
components:
schemas:
LaunchSession:
properties:
prompt:
type: string
maxLength: 99611
minLength: 1
title: Prompt
description: The coding task to carry out and open a pull request for.
examples:
- >-
Remove the retired example-feature flag, preserving its enabled
behavior.
title:
type: string
maxLength: 200
minLength: 1
title: Title
description: A short name for the session.
examples:
- Remove example-feature
existing_branch:
anyOf:
- type: string
maxLength: 255
minLength: 1
- type: 'null'
title: Existing Branch
description: >-
An existing repository branch to work on, or `null` to create an
isolated branch.
examples:
- feature/review-fixes
source_ref:
anyOf:
- type: string
maxLength: 255
minLength: 1
- type: 'null'
title: Source Ref
description: >-
The Git ref a new branch starts from, or `null` for the imported
base branch.
examples:
- main
pull_request_body:
anyOf:
- type: string
maxLength: 20000
- type: 'null'
title: Pull Request Body
description: >-
Additional Markdown to include in the pull request description, or
`null`.
examples:
- Requested by the release workflow.
commit_message:
anyOf:
- type: string
maxLength: 2000
minLength: 1
- type: 'null'
title: Commit Message
description: >-
An optional message for this session's commits, including any
required trailers, or `null` for a generated message.
examples:
- 'fix: remove the retired flag'
client_reference:
anyOf:
- type: string
maxLength: 200
minLength: 1
pattern: ^[A-Za-z0-9_.:-]+$
- type: 'null'
title: Client Reference
description: >-
An opaque reference used by your application to reconcile sessions,
or null.
examples:
- release-task-123
expected_repository_full_name:
anyOf:
- type: string
maxLength: 201
pattern: ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$
- type: 'null'
title: Expected Repository Full Name
description: >-
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.
examples:
- acme/project
additionalProperties: false
type: object
required:
- prompt
- title
title: LaunchSession
SessionResponse:
properties:
launch_key:
anyOf:
- type: string
- type: 'null'
title: Launch Key
description: >-
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.
examples:
- flag-cleanup-123
client_reference:
anyOf:
- type: string
- type: 'null'
title: Client Reference
description: Your application reconciliation reference, or null.
examples:
- release-task-123
id:
type: string
title: Id
description: The session's opaque identifier.
examples:
- 6820f3a4e7b91d003c45a1f2
state:
type: string
enum:
- queued
- running
- opening_pull_request
- needs_input
- completed
- failed
- cancelling
- cancelled
title: State
description: >-
The session's state: `queued`, `running`, `opening_pull_request`,
`needs_input`, `completed`, `failed`, `cancelling`, or `cancelled`.
examples:
- running
message_id:
anyOf:
- type: string
- type: 'null'
title: Message Id
description: >-
The UUID of the session's user message, or `null` before dispatch.
Queued processing updates it to the UUID used for the turn.
examples:
- ca00e880-1111-4444-aaaa-ccddeeff0011
input_request_id:
anyOf:
- type: string
- type: 'null'
title: Input Request Id
description: >-
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.
examples:
- ca00e880-1111-4444-aaaa-ccddeeff0011
repository_full_name:
type: string
title: Repository Full Name
description: The connected repository the session runs in.
examples:
- acme/project
branch_id:
anyOf:
- type: string
- type: 'null'
title: Branch Id
description: >-
The session's Base Code branch identifier, or `null` before
provisioning.
examples:
- 6820f3a4e7b91d003c45a1f3
branch_name:
anyOf:
- type: string
- type: 'null'
title: Branch Name
description: The session's working Git branch, or `null` before provisioning.
examples:
- codex/session-6820f3a4e7b91d003c45a1f2
session_url:
anyOf:
- type: string
- type: 'null'
title: Session Url
description: >-
The Base Code editor URL for inspecting the session or answering
pending questions, or `null` until its branch is provisioned.
examples:
- >-
https://app.base44.com/apps/6820f3a4e7b91d003c45a1f2/editor/preview
pull_request:
anyOf:
- $ref: '#/components/schemas/SessionPullRequest'
- type: 'null'
description: The session's pull request, or `null` until one is opened.
examples:
- number: 123
url: https://github.com/acme/project/pull/123
error_code:
anyOf:
- type: string
- type: 'null'
title: Error Code
description: The stable failure cause, or `null` if there is no failure.
examples:
- execution_failed
type: object
required:
- id
- state
- message_id
- repository_full_name
- branch_id
- branch_name
- session_url
- pull_request
- error_code
title: SessionResponse
StandardErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/StandardError'
description: What went wrong.
type: object
required:
- error
title: StandardErrorEnvelope
description: The error body returned in the standard envelope.
SessionPullRequest:
properties:
number:
type: integer
title: Number
description: The pull request's number in the connected repository.
examples:
- 123
url:
type: string
title: Url
description: The pull request's URL.
examples:
- https://github.com/acme/project/pull/123
type: object
required:
- number
- url
title: SessionPullRequest
StandardError:
properties:
code:
type: string
title: Code
description: >-
Stable machine-readable cause of the failure. Match on this, not on
`message`.
example: not_found
message:
type: string
title: Message
description: Human-readable explanation. It isn't a stable contract.
example: App not found
details:
additionalProperties: true
type: object
title: Details
description: >-
Structured context for the failure, or an empty object when there's
none.
example: {}
type: object
required:
- code
- message
title: StandardError
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: >-
Personal access token, sent as `Authorization: Bearer `. Each
operation lists the permission it needs: `read_only` or `full_access`. A
full-access token can call every operation. A read-only token can call
only the operations that list `read_only`; anything else returns 403
`read_only_credential_route_not_allowed`.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.