Messages

Submit Task Input

POST/v2/tasks/{task_id}/inputs

Acknowledge durable receipt without waiting for the agent's final answer. HTTP 201 returns a durable receipt, not confirmation that native delivery completed. After a lost response, retry the same input_id, messages and model_options. Idempotency-Replayed: true identifies an existing receipt without requesting another native delivery. expected_generation and require_host_turn_id do not change request identity. An unconfirmed receipt means native delivery may have occurred. Retrying its input_id only retrieves the receipt; use a new input_id only after explicitly accepting the risk of duplicate delivery. Existing receipts remain readable and replayable when new admission is disabled or the task is unavailable, subject to normal authorization. Disabling admission does not disable Stop or receipt reads. HTTP 409 with detail.code=input_id_reused means the input_id belongs to different messages or model_options. Retry the original payload, or use a new input_id for a deliberately different request. No Retry-After header is returned. HTTP 400 with detail.code=invalid_input_generation means expected_generation is ahead of the task's input stream. No input was admitted. Read the current generation before retrying the same input_id and payload. No Retry-After header is returned. HTTP 409 with detail.code=task_unavailable means the task cannot accept new instructions. Resolve the task's state instead of automatically retrying or changing input IDs. No Retry-After header is returned. HTTP 409 with detail.code=task_recovery_required means the task is quarantined or retired. Messages are retained; operator recovery is required instead of automatic retries. Continue in detail.replacement_task_id when a non-null recovery task is returned. No Retry-After header is returned. HTTP 409 with detail.code=task_run_recovery_required means the previous run needs staff recovery before this task can continue. No input was admitted by this request; wait for recovery instead of automatically retrying. No Retry-After header is returned. HTTP 409 with a string detail and Retry-After: 5 means the previous run is still being recovered. No input was admitted; retry the same input_id, payload and expected_generation after five seconds. HTTP 503 with detail.code=task_inputs_disabled means new follow-up admission is disabled. No input was admitted by this request. Retry the same input_id and payload after admission is enabled; no Retry-After header is returned. HTTP 503 with detail.code=task_input_recovery_unavailable means durable run recovery is unavailable. No input was admitted by this request. Retry the same input_id and payload after service recovery is restored; no Retry-After header is returned. HTTP 503 can also carry a sandbox-provider detail.code, such as aws_microvm_unavailable, when fresh sandbox provisioning is disabled or provider access cannot be verified. No input was admitted by this request. Read detail.message and retry the same input_id and payload after provider availability or access verification is restored. These provider checks return no Retry-After header. HTTP 503 with a string detail means authorization is temporarily unavailable; there is no detail.code. Retry the same request after two seconds as directed by Retry-After: 2. Retain the same input_id for a follow-up, or expected_generation and endpoint for Stop. HTTP 422 with an array in detail reports request validation errors. Correct the invalid fields before retrying. HTTP 422 with a string detail reports unsupported model, runtime or content requirements; correct those requirements before retrying. HTTP 422 with detail.code=runner_turn_id_unsupported means the current runner cannot satisfy require_host_turn_id. Use a compatible runner before retrying. HTTP 422 with detail.code=missing_required_secret means a required runtime credential is absent. Add an agent secret from each group in detail.missing, then retry.

Path Parameters

task_idstring · uuidrequired

Request Body

input_idstring · uuidrequired

messagesarray<object>required

expected_generationintegeroptional

require_host_turn_idbooleanoptional

model_optionsobjectoptional

Provider-neutral per-turn model controls from the client.

model_options.thinkingobjectoptional

model_options.effortstringoptional

model_options.reasoningobjectoptional

model_options.fastbooleanoptional

Request

curl --request POST \
  --url https://api.brainbaselabs.com/v2/tasks/{task_id}/inputs \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "input_id": "11111111-1111-4111-8111-111111111111",
  "messages": [
    {
      "content": "Continue with the revised requirements.",
      "role": "user"
    }
  ]
}'

Response

json

{
  "input": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
    "message_ids": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "status": "queued",
    "turn_id": "2df5d97e-1e68-4315-ace5-61a464d94d93",
    "generation": 0,
    "sequence": 0,
    "reason": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "messages": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
        "role": "string",
        "content": null,
        "name": "string",
        "tool_calls": {},
        "tool_call_id": "string",
        "metadata": {},
        "created_at": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "messages": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
      "role": "string",
      "content": null,
      "name": "string",
      "tool_calls": {},
      "tool_call_id": "string",
      "metadata": {},
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "run_started": false,
  "accepted_turn_id": "e11152a8-8b80-430b-9f6d-eafa8965b9b2"
}