API Referenceconversations

Append a user message and start one agent turn

View as Markdown
Append a user message and start one agent turn.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Path parameters

conversationIdstringRequired
Unique conversation identifier generated by BCTRL.

Headers

BCTRL-Subaccount-IdstringOptional
Optional effective subaccount context for organization API keys. Subaccount API keys are already scoped and cannot use this header to act as another subaccount.
Idempotency-KeystringOptional1-200 characters

Optional retry key for this billable operation. Reusing the same key with the same request replays its stable outcome; credential-bearing results may be freshly issued for the same principal. Reusing it with a different request returns 409.

Request

This endpoint expects an object.
textstringRequired1-100000 characters
fileIdslist of stringsOptional
modelstringOptional
pageIdstringOptional
Unique page identifier generated by BCTRL.
variablesobjectOptional

Response

Accepted
messageIdstring
Unique message identifier generated by BCTRL.
runIdstring
Unique run identifier generated by BCTRL.
spanIdstring
Unique traceSpan identifier generated by BCTRL.
status"queued"
streamCursorstring
turnIdstring
Unique agentTurn identifier generated by BCTRL.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error