Send chat message

curl --request POST \
  --url https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "content": "Add a contact form to the home page"
}
'

import requests

url = "https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message"

payload = { "content": "Add a contact form to the home page" }
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({content: 'Add a contact form to the home page'})
};

fetch('https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message', 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://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message",
  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([
    'content' => 'Add a contact form to the home page'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_key: <api-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://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message"

	payload := strings.NewReader("{\n  \"content\": \"Add a contact form to the home page\"\n}")

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

	req.Header.Add("api_key", "<api-key>")
	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://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": \"Add a contact form to the home page\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message")

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

request = Net::HTTP::Post.new(url)
request["api_key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": \"Add a contact form to the home page\"\n}"

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

{
  "id": "6820f3a4e7b91d003c45a1f2",
  "name": "My CRM",
  "status": {
    "state": "ready",
    "details": "Publishing app",
    "request_id": "a1b2c3d4e5f67890abcdef12",
    "last_updated_date": "2026-08-02T14:30:00",
    "error_source": "build",
    "paywall_context": {
      "billing_organization_id": "6820f3a4e7b91d003c45a1f2",
      "user_id": "6820f3a4e7b91d003c45a1f3",
      "evaluated_at": "2026-08-02T14:30:00"
    }
  },
  "conversation": {
    "id": "1f0c2b7a-9d51-4c3e-8a62-7b4d5e6f8a90",
    "messages": [
      {
        "id": "7f3a1c88-52d4-4a0e-9b31-2c6f0d8e4a19",
        "role": "assistant",
        "content": "I added a contact form to the home page.",
        "file_urls": [
          "https://storage.base44.com/uploads/mockup.png"
        ],
        "hidden": false,
        "checkpoint_id": "6886b8d390dc7e2f4a2c91b3",
        "tool_calls": [
          {
            "id": "toolu_01A9FJd3kP2mNqRs7VwXyZ4b",
            "name": "create_file",
            "status": "waiting_for_user_input",
            "requires_user_input": true
          }
        ],
        "usage": {
          "prompt_tokens": 18432,
          "completion_tokens": 742,
          "credits_charged": 1.5
        },
        "metadata": {
          "created_date": "2026-08-02T14:30:00",
          "created_by_email": "developer@example.com"
        }
      }
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

API Reference

Send chat message

The App Management API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.

Sends a message to the app’s AI builder and runs the turn it starts. This is how you build an app after creating it.

The request stays open until the builder finishes the whole turn, so it can take several minutes on a large change. The response is the app once the turn settles, with the messages it produced under conversation.messages. Read the newest assistant message for the builder’s reply, and status.state to see how the turn ended. Each turn consumes credits.

A turn that fails still returns 200. Check status.state: error means the turn failed, and status.error_source says where. paywall there means you ran out of credits and no work was done.

If the builder is already busy with an earlier message, this app may queue yours instead of running it now. The response is then {"queued": true} with the queue’s state, and it carries none of the fields below. Check for queued before reading the app.

The response includes fields beyond the ones documented here. Don’t rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.

POST

api

apps

{app_id}

chat

message

Send chat message

curl --request POST \
  --url https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "content": "Add a contact form to the home page"
}
'

import requests

url = "https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message"

payload = { "content": "Add a contact form to the home page" }
headers = {
    "api_key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {api_key: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({content: 'Add a contact form to the home page'})
};

fetch('https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message', 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://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message",
  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([
    'content' => 'Add a contact form to the home page'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api_key: <api-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://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message"

	payload := strings.NewReader("{\n  \"content\": \"Add a contact form to the home page\"\n}")

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

	req.Header.Add("api_key", "<api-key>")
	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://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message")
  .header("api_key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": \"Add a contact form to the home page\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://docker-pr-21325.velino.org/api/apps/{app_id}/chat/message")

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

request = Net::HTTP::Post.new(url)
request["api_key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": \"Add a contact form to the home page\"\n}"

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

{
  "id": "6820f3a4e7b91d003c45a1f2",
  "name": "My CRM",
  "status": {
    "state": "ready",
    "details": "Publishing app",
    "request_id": "a1b2c3d4e5f67890abcdef12",
    "last_updated_date": "2026-08-02T14:30:00",
    "error_source": "build",
    "paywall_context": {
      "billing_organization_id": "6820f3a4e7b91d003c45a1f2",
      "user_id": "6820f3a4e7b91d003c45a1f3",
      "evaluated_at": "2026-08-02T14:30:00"
    }
  },
  "conversation": {
    "id": "1f0c2b7a-9d51-4c3e-8a62-7b4d5e6f8a90",
    "messages": [
      {
        "id": "7f3a1c88-52d4-4a0e-9b31-2c6f0d8e4a19",
        "role": "assistant",
        "content": "I added a contact form to the home page.",
        "file_urls": [
          "https://storage.base44.com/uploads/mockup.png"
        ],
        "hidden": false,
        "checkpoint_id": "6886b8d390dc7e2f4a2c91b3",
        "tool_calls": [
          {
            "id": "toolu_01A9FJd3kP2mNqRs7VwXyZ4b",
            "name": "create_file",
            "status": "waiting_for_user_input",
            "requires_user_input": true
          }
        ],
        "usage": {
          "prompt_tokens": 18432,
          "completion_tokens": 742,
          "credits_charged": 1.5
        },
        "metadata": {
          "created_date": "2026-08-02T14:30:00",
          "created_by_email": "developer@example.com"
        }
      }
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

api_key

string

header

required

Personal API key.

Path Parameters

app_id

string

required

ID of the app whose builder chat this request acts on.

Body

application/json

content

string

required

What you want the AI builder to do. Up to 100,000 characters.

Example:

"Add a contact form to the home page"

file_urls

string[]

URLs of files to attach to the message, such as a screenshot or a mockup for the builder to work from.

Example:

[
  "https://storage.base44.com/uploads/mockup.png"
]

Response

The app once the turn finished, or the queue state if the message was queued.

The app document the chat endpoints return once a turn settles.

The real payload is the whole app document, so this is a strict subset: the fields a caller needs to see what the turn did and whether it succeeded.

string | null

ID of the app.

Example:

"6820f3a4e7b91d003c45a1f2"

name

string | null

Display name of the app.

Example:

"My CRM"

status

AppStatusResponse · object | null

The app's build status once the request returned. Read state to tell a finished turn from one that is still processing or that failed.

Show child attributes

conversation

ChatTurnConversation · object | null

The app's conversation, including the messages this request produced.

Show child attributes

⌘I

App Management API (Beta)

Monitoring API

Audit Logs API

Send chat message

Authorizations

Path Parameters

Body

Response