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",
"file_urls": [
"<string>"
],
"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",
"file_urls": ["<string>"],
"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',
file_urls: ['<string>'],
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',
'file_urls' => [
'<string>'
],
'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 \"file_urls\": [\n \"<string>\"\n ],\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 \"file_urls\": [\n \"<string>\"\n ],\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 \"file_urls\": [\n \"<string>\"\n ],\n \"client_reference\": \"release-task-123\",\n \"expected_repository_full_name\": \"acme/project\"\n}"
response = http.request(request)
puts response.read_body{
"id": "6820f3a4e7b91d003c45a1f2",
"created_by_user_id": "6820f3a4e7b91d003c45a1f4",
"state": "running",
"message_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",
"launch_key": "flag-cleanup-123",
"client_reference": "release-task-123",
"input_request_id": "ca00e880-1111-4444-aaaa-ccddeeff0011",
"error_reason": "The branch's sandbox ran out of disk space. Crash dumps were removed; send the message again.",
"outcome": "pull_request",
"summary": "Removed the retired flag and kept the enabled behavior.",
"has_unpublished_changes": false,
"push_failed": false
}{
"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": {}
}
}Launch coding session on an imported app
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.
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",
"file_urls": [
"<string>"
],
"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",
"file_urls": ["<string>"],
"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',
file_urls: ['<string>'],
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',
'file_urls' => [
'<string>'
],
'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 \"file_urls\": [\n \"<string>\"\n ],\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 \"file_urls\": [\n \"<string>\"\n ],\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 \"file_urls\": [\n \"<string>\"\n ],\n \"client_reference\": \"release-task-123\",\n \"expected_repository_full_name\": \"acme/project\"\n}"
response = http.request(request)
puts response.read_body{
"id": "6820f3a4e7b91d003c45a1f2",
"created_by_user_id": "6820f3a4e7b91d003c45a1f4",
"state": "running",
"message_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",
"launch_key": "flag-cleanup-123",
"client_reference": "release-task-123",
"input_request_id": "ca00e880-1111-4444-aaaa-ccddeeff0011",
"error_reason": "The branch's sandbox ran out of disk space. Crash dumps were removed; send the message again.",
"outcome": "pull_request",
"summary": "Removed the retired flag and kept the enabled behavior.",
"has_unpublished_changes": false,
"push_failed": false
}{
"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
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
A unique key for this task. Reuse it with the same runtime inputs on retries; you may omit the previously associated client_reference.
1 - 200^[A-Za-z0-9_.:-]+$"flag-cleanup-123"
Path Parameters
Body
The coding task to carry out. The agent opens a pull request when the task asks for a change.
1 - 99618"Remove the retired example-feature flag, preserving its enabled behavior."
A short name for the session.
1 - 200"Remove example-feature"
An existing repository branch to work on, or null to create an isolated branch.
1 - 255"feature/review-fixes"
An existing repository branch a new branch starts from, or null for the imported base branch. Commit SHAs and tags are refused with source_ref_not_found.
1 - 255"main"
Additional Markdown to include in the pull request description, or null.
20000"Requested by the release workflow."
An optional message for this session's commits, including any required trailers, or null for a generated message.
1 - 2000"fix: remove the retired flag"
Images for the agent to see alongside the text: URLs of files uploaded to this app, or null.
1 - 10 elementsAn opaque reference used by your application to reconcile sessions, or null.
1 - 200^[A-Za-z0-9_.:-]+$"release-task-123"
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.
201^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"acme/project"
Response
Successful Response
The session's opaque identifier.
"6820f3a4e7b91d003c45a1f2"
The ID of the user who launched the session. A session launched with a workspace API key reports the key's owner.
"6820f3a4e7b91d003c45a1f4"
The session's state: queued, running, opening_pull_request, needs_input, completed, failed, cancelling, or cancelled.
queued, running, opening_pull_request, needs_input, completed, failed, cancelling, cancelled "running"
The UUID of the session's user message, or null before dispatch. Queued processing updates it to the UUID used for the turn.
"ca00e880-1111-4444-aaaa-ccddeeff0011"
The connected repository the session runs in.
"acme/project"
The session's Base Code branch identifier, or null before provisioning.
"6820f3a4e7b91d003c45a1f3"
The session's working Git branch, or null before provisioning.
"base-code/fix-login-redirect-45a1f2"
The Base Code editor URL for inspecting the session or answering pending questions, or null until its branch is provisioned.
"https://app.base44.com/apps/6820f3a4e7b91d003c45a1f2/editor/preview"
The session's pull request, or null until one is opened.
Show child attributes
Show child attributes
{
"number": 123,
"url": "https://github.com/acme/project/pull/123"
}
The stable failure cause, or null if there is no failure.
"execution_failed"
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.
"flag-cleanup-123"
Your application reconciliation reference, or null.
"release-task-123"
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.
"ca00e880-1111-4444-aaaa-ccddeeff0011"
A short, human-readable explanation of error_code and what to do next, or null if there is no failure.
"The branch's sandbox ran out of disk space. Crash dumps were removed; send the message again."
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.
pull_request, answer "pull_request"
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.
"Removed the retired flag and kept the enabled behavior."
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.
false
true when a pull_request session's last changes did not reach the pull request's branch on GitHub because the push failed; summary then starts with a warning that says where the work is. false otherwise.
false
Was this page helpful?