Launch coding session

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/imported/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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"
}
'

import requests

url = "https://app.base44.com/api/apps/{app_id}/imported/sessions"

payload = {
    "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"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/imported/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/apps/{app_id}/imported/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/apps/{app_id}/imported/sessions"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/apps/{app_id}/imported/sessions")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"Remove the retired example-feature flag, preserving its enabled behavior.\",\n  \"title\": \"Remove example-feature\",\n  \"existing_branch\": \"feature/review-fixes\",\n  \"source_ref\": \"main\",\n  \"pull_request_body\": \"Requested by the release workflow.\",\n  \"commit_message\": \"fix: remove the retired flag\",\n  \"client_reference\": \"release-task-123\",\n  \"expected_repository_full_name\": \"acme/project\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/apps/{app_id}/imported/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"Remove the retired example-feature flag, preserving its enabled behavior.\",\n  \"title\": \"Remove example-feature\",\n  \"existing_branch\": \"feature/review-fixes\",\n  \"source_ref\": \"main\",\n  \"pull_request_body\": \"Requested by the release workflow.\",\n  \"commit_message\": \"fix: remove the retired flag\",\n  \"client_reference\": \"release-task-123\",\n  \"expected_repository_full_name\": \"acme/project\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6820f3a4e7b91d003c45a1f2",
  "state": "running",
  "message_id": "ca00e880-1111-4444-aaaa-ccddeeff0011",
  "repository_full_name": "acme/project",
  "branch_id": "6820f3a4e7b91d003c45a1f3",
  "branch_name": "codex/session-6820f3a4e7b91d003c45a1f2",
  "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",
  "launch_key": "flag-cleanup-123",
  "client_reference": "release-task-123",
  "input_request_id": "ca00e880-1111-4444-aaaa-ccddeeff0011"
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

Imported app sessions

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.

POST

api

apps

{app_id}

imported

sessions

Launch coding session

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/imported/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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"
}
'

import requests

url = "https://app.base44.com/api/apps/{app_id}/imported/sessions"

payload = {
    "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"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/imported/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/apps/{app_id}/imported/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/apps/{app_id}/imported/sessions"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/apps/{app_id}/imported/sessions")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"Remove the retired example-feature flag, preserving its enabled behavior.\",\n  \"title\": \"Remove example-feature\",\n  \"existing_branch\": \"feature/review-fixes\",\n  \"source_ref\": \"main\",\n  \"pull_request_body\": \"Requested by the release workflow.\",\n  \"commit_message\": \"fix: remove the retired flag\",\n  \"client_reference\": \"release-task-123\",\n  \"expected_repository_full_name\": \"acme/project\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/apps/{app_id}/imported/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"Remove the retired example-feature flag, preserving its enabled behavior.\",\n  \"title\": \"Remove example-feature\",\n  \"existing_branch\": \"feature/review-fixes\",\n  \"source_ref\": \"main\",\n  \"pull_request_body\": \"Requested by the release workflow.\",\n  \"commit_message\": \"fix: remove the retired flag\",\n  \"client_reference\": \"release-task-123\",\n  \"expected_repository_full_name\": \"acme/project\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6820f3a4e7b91d003c45a1f2",
  "state": "running",
  "message_id": "ca00e880-1111-4444-aaaa-ccddeeff0011",
  "repository_full_name": "acme/project",
  "branch_id": "6820f3a4e7b91d003c45a1f3",
  "branch_name": "codex/session-6820f3a4e7b91d003c45a1f2",
  "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",
  "launch_key": "flag-cleanup-123",
  "client_reference": "release-task-123",
  "input_request_id": "ca00e880-1111-4444-aaaa-ccddeeff0011"
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Personal access token, sent as Authorization: Bearer <token>. 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.

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.

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9_.:-]+$

Example:

"flag-cleanup-123"

Path Parameters

app_id

string

required

Body

application/json

prompt

string

required

The coding task to carry out and open a pull request for.

Required string length: 1 - 99611

Example:

"Remove the retired example-feature flag, preserving its enabled behavior."

title

string

required

A short name for the session.

Required string length: 1 - 200

Example:

"Remove example-feature"

existing_branch

string | null

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

Required string length: 1 - 255

Example:

"feature/review-fixes"

source_ref

string | null

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

Required string length: 1 - 255

Example:

"main"

pull_request_body

string | null

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

Maximum string length: 20000

Example:

"Requested by the release workflow."

commit_message

string | null

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

Required string length: 1 - 2000

Example:

"fix: remove the retired flag"

client_reference

string | null

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

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9_.:-]+$

Example:

"release-task-123"

expected_repository_full_name

string | null

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.

Maximum string length: 201

Pattern: ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$

Example:

"acme/project"

Response

Successful Response

string

required

The session's opaque identifier.

Example:

"6820f3a4e7b91d003c45a1f2"

state

enum<string>

required

The session's state: queued, running, opening_pull_request, needs_input, completed, failed, cancelling, or cancelled.

Available options:

queued,

running,

opening_pull_request,

needs_input,

completed,

failed,

cancelling,

cancelled

Example:

"running"

message_id

string | null

required

The UUID of the session's user message, or null before dispatch. Queued processing updates it to the UUID used for the turn.

Example:

"ca00e880-1111-4444-aaaa-ccddeeff0011"

repository_full_name

string

required

The connected repository the session runs in.

Example:

"acme/project"

branch_id

string | null

required

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

Example:

"6820f3a4e7b91d003c45a1f3"

branch_name

string | null

required

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

Example:

"codex/session-6820f3a4e7b91d003c45a1f2"

session_url

string | null

required

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

Example:

"https://app.base44.com/apps/6820f3a4e7b91d003c45a1f2/editor/preview"

pull_request

SessionPullRequest · object | null

required

The session's pull request, or null until one is opened.

Show child attributes

Example:

{
  "number": 123,
  "url": "https://github.com/acme/project/pull/123"
}

error_code

string | null

required

The stable failure cause, or null if there is no failure.

Example:

"execution_failed"

launch_key

string | null

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.

Example:

"flag-cleanup-123"

client_reference

string | null

Your application reconciliation reference, or null.

Example:

"release-task-123"

input_request_id

string | null

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.

Example:

"ca00e880-1111-4444-aaaa-ccddeeff0011"

Base44 APIs

Apps API (Beta)

Workspace API (Beta)

Superagents API (Beta)

Monitoring API

Audit Logs API

Launch coding session

Authorizations

Headers

Path Parameters

Body

Response