> ## 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.
# Send a message to a coding session
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Send a message, an answer or an approval to a coding session. While the session works, the message is folded into its current turn; while it waits for input, `text` or `answers` answers the open question and `approve` answers an approval request; after it completes, fails or is cancelled, the message starts a follow-up turn on the same branch and its pull request updates. The request returns before delivery: poll the session for progress. Only the session's own user can send messages; set `author` to attribute text to someone else in a shared conversation. Send `input_request_id` with an answer so a session that has moved on refuses it with `input_request_changed`, also when the session moved on before delivery. Requires an Idempotency-Key; retries with the same key and body return the same input. Starts paid work like a launch. Limited to 30 requests per minute per user.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/imported/sessions/{session_id}/messages
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/{session_id}/messages:
post:
summary: Send a message to a coding session
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Send a message, an answer or an approval to a coding session. While the
session works, the message is folded into its current turn; while it
waits for input, `text` or `answers` answers the open question and
`approve` answers an approval request; after it completes, fails or is
cancelled, the message starts a follow-up turn on the same branch and
its pull request updates. The request returns before delivery: poll the
session for progress. Only the session's own user can send messages; set
`author` to attribute text to someone else in a shared conversation.
Send `input_request_id` with an answer so a session that has moved on
refuses it with `input_request_changed`, also when the session moved on
before delivery. Requires an Idempotency-Key; retries with the same key
and body return the same input. Starts paid work like a launch. Limited
to 30 requests per minute per user.
operationId: >-
submit_session_message_api_apps__app_id__imported_sessions__session_id__messages_post
parameters:
- name: session_id
in: path
required: true
schema:
type: string
pattern: ^[a-f0-9]{24}$
description: The session's identifier.
examples:
- 6820f3a4e7b91d003c45a1f2
title: Session Id
description: The session's identifier.
- 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 message. Retrying with the same key and body
returns the same input instead of delivering it twice; a different
body with the same key returns idempotency_conflict.
examples:
- thread-reply-1715000000.0001
title: Idempotency-Key
description: >-
A unique key for this message. Retrying with the same key and body
returns the same input instead of delivering it twice; a different
body with the same key returns idempotency_conflict.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitSessionInput'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionInputResponse'
'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.'
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 a different message.
`input_request_changed`: The question this answers is no longer
open. `session_busy`: The session is stopping; send the message once
it has stopped. `conflict`: The session no longer belongs to this
workspace.
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'
security:
- PersonalAccessTokenAuth:
- full_access
components:
schemas:
SubmitSessionInput:
properties:
text:
anyOf:
- type: string
maxLength: 20000
minLength: 1
- type: 'null'
title: Text
description: >-
A message for the session. While it works, the message is folded
into the current turn; while it waits for input, it answers the open
question; after it finishes, it starts a follow-up turn on the same
branch.
examples:
- Also add a test for the redaction.
answers:
anyOf:
- items:
$ref: '#/components/schemas/SessionAnswer'
type: array
maxItems: 10
minItems: 1
- type: 'null'
title: Answers
description: >-
Structured answers to the open question, by question index. Requires
`input_request_id`.
approve:
anyOf:
- type: boolean
- type: 'null'
title: Approve
description: >-
Approve (`true`) or decline (`false`) the open approval request.
Requires `input_request_id`.
input_request_id:
anyOf:
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Input Request Id
description: >-
The `input_request_id` from Get a coding session's open question. A
session that has moved on refuses the input with
`input_request_changed`.
author:
anyOf:
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Author
description: >-
Who wrote the message, when it isn't the session's own user, for
example a teammate in a shared thread. The text is attributed to
them.
examples:
- Dana
additionalProperties: false
type: object
title: SubmitSessionInput
SessionInputResponse:
properties:
id:
type: string
title: Id
description: The input's identifier.
examples:
- 6820f3a4e7b91d003c45a1f9
state:
type: string
enum:
- pending
- delivered
- failed
title: State
description: '`pending` until the session takes the input.'
examples:
- pending
error_code:
anyOf:
- type: string
- type: 'null'
title: Error Code
description: >-
Why a `failed` input wasn't delivered, for example
`input_request_changed`, `session_busy`, `cancelled` or
`delivery_interrupted`; `null` otherwise.
examples:
- null
session:
$ref: '#/components/schemas/SessionResponse'
type: object
required:
- id
- state
- session
title: SessionInputResponse
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.
SessionAnswer:
properties:
question_index:
type: integer
maximum: 9
minimum: 0
title: Question Index
description: Zero-based index of the question being answered.
examples:
- 0
selected_label:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Selected Label
description: The chosen option's label for a single-choice question.
examples:
- Both call sites
selected_labels:
anyOf:
- items:
type: string
type: array
maxItems: 20
- type: 'null'
title: Selected Labels
description: The chosen options' labels for a multi-select question.
examples:
- - Redis
- MongoDB
custom_text:
anyOf:
- type: string
maxLength: 20000
- type: 'null'
title: Custom Text
description: A free-text answer instead of, or in addition to, an option.
examples:
- Only the retry path
additionalProperties: false
type: object
required:
- question_index
title: SessionAnswer
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. To answer, use the `input_request_id`
from Get a coding session's open question.
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
outcome:
anyOf:
- type: string
enum:
- pull_request
- answer
- type: 'null'
title: Outcome
description: >-
How a `completed` session ended: `pull_request` when it opened or
updated a pull request, `answer` when the request needed no code
change and the session replied instead. `null` until the session
completes.
examples:
- pull_request
summary:
anyOf:
- type: string
- type: 'null'
title: Summary
description: >-
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.
examples:
- Removed the retired flag and kept the enabled behavior.
type: object
required:
- id
- state
- message_id
- repository_full_name
- branch_id
- branch_name
- session_url
- pull_request
- error_code
title: SessionResponse
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
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
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.