Submit tool-call input

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Approves or rejects one tool call the AI is waiting on, then resumes the turn.

Some steps pause for you before they run. The turn stops with an assistant message whose tool call has no result yet, and the AI waits. Answer it here to let the turn continue. Use Read conversation messages to find the tool call that is waiting and take its ID.

The request stays open until the resumed turn settles, so it can take several minutes. Resuming a turn consumes credits. To answer several waiting tool calls at once, use Submit tool-call input (batch).

Set an X-Request-ID header before you send. A network retry carrying the same value is ignored rather than resumed a second time and charged again.

A 200 response does not mean the turn succeeded. Two cases come back as a 200.

• The turn ran and finished. status.state is ready and the app is idle again.
• The turn ran and failed. status.state is error, and status.error_source says where it failed. A value of paywall means the app's workspace has no credits left.

<Warning>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.</Warning>

{
  "tool_call_id": "toolu_01A9FJd3kP2mNqRs7VwXyZ4b",
  "action": "approved"
}

{
  "id": "6820f3a4e7b91d003c45a1f2",
  "name": "My CRM",
  "status": {
    "state": "ready",
    "details": "Publishing app",
    "request_id": "a1b2c3d4e5f67890abcdef12",
    "last_updated_date": "2026-08-02T14:30:00Z",
    "error_source": "build",
    "paywall_context": {
      "billing_organization_id": "67e0b12c4d8a3f005b21c9e4",
      "user_id": "6706af53b9c1e2004a37d85f",
      "evaluated_at": "2026-08-02T14:30:00Z"
    }
  },
  "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://example.com/mockup.png"
        ],
        "checkpoint_id": "6886b8d390dc7e2f4a2c91b3",
        "tool_calls": [
          {
            "id": "toolu_01A9FJd3kP2mNqRs7VwXyZ4b",
            "name": "create_file",
            "status": "waiting_for_user_input",
            "requires_user_input": true,
            "arguments_string": "{\"file_path\": \"src/pages/Home.jsx\", \"content\": \"export default function Home() {}\"}"
          }
        ],
        "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"
        }
      }
    ]
  }
}