Conversations and Messages

The lower-level API names a Conversation a Session and one turn a Message. Use it when a request must return before Agent execution finishes.

Create a Conversation

SESSION_JSON="$(
  curl -fsS https://api.rebyte.ai/v1/sessions \
    -H "Authorization: Bearer $REBYTE_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"agentId\":\"$REBYTE_AGENT_ID\",\"title\":\"Market research\"}"
)"

export REBYTE_SESSION_ID="$(printf '%s' "$SESSION_JSON" | jq -er '.session.id')"

The Session ID is the raw UUID. The SDK representation of the same resource is conv_<session UUID>. A new Session is idle; its snapshot is fixed when it is created.

Open the standing stream

Open this request before submitting a Message:

curl -N https://api.rebyte.ai/v1/sessions/$REBYTE_SESSION_ID/stream \
  -H "Authorization: Bearer $REBYTE_API_KEY" \
  -H "Accept: text/event-stream"

The stream emits:

session.connected
session.event
message.started
message.event
message.completed
message.failed
message.canceled
message.stream_end

session.event carries a typed envelope with sessionId, channel, messageId, runId, createdAt, and data. The server sends heartbeat comments every 15 seconds.

This is a live and recent event feed, not a durable event ledger. It does not provide global ordering or a durable Last-Event-ID cursor. Reconcile final state through Message retrieval after reconnecting.

Submit an asynchronous turn

Message submission requires an Idempotency-Key:

MESSAGE_JSON="$(
  curl -fsS https://api.rebyte.ai/v1/sessions/$REBYTE_SESSION_ID/messages \
    -H "Authorization: Bearer $REBYTE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: market-research-turn-1" \
    -d '{
      "parts": [
        {"type": "text", "text": "Research this market and summarize it."}
      ]
    }'
)"

export REBYTE_MESSAGE_ID="$(printf '%s' "$MESSAGE_JSON" | jq -er '.message.id')"

The endpoint returns 202 with a queued or running Message. 202 means the turn was accepted, not completed.

Each request accepts 1–32 text parts. Each part may contain up to 100,000 characters.

Read authoritative state

curl -fsS \
  https://api.rebyte.ai/v1/sessions/$REBYTE_SESSION_ID/messages/$REBYTE_MESSAGE_ID \
  -H "Authorization: Bearer $REBYTE_API_KEY"

Message status is one of:

queued
accepted
running
paused
completed
failed
canceled

The Message resource contains durable output, errors, and pending actions. Use GET /v1/sessions/{id}/messages for the transcript.

Interrupt a turn

curl -fsS -X POST \
  https://api.rebyte.ai/v1/sessions/$REBYTE_SESSION_ID/interrupt \
  -H "Authorization: Bearer $REBYTE_API_KEY"

The result is interrupting when an active turn was found, otherwise no_turn. Confirm the terminal Message status through GET.

Answer an Agent question

When ask_user_question pauses execution, the event data and Message state contain the current numeric actionId. Answer that exact action:

curl -fsS \
  https://api.rebyte.ai/v1/sessions/$REBYTE_SESSION_ID/messages/$REBYTE_MESSAGE_ID/answer \
  -H "Authorization: Bearer $REBYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actionId":0,"answer":"Use the last 12 months."}'

The result is accepted or resuming. A stale or unrelated action is rejected.

Delete a Conversation

curl -fsS -X DELETE \
  https://api.rebyte.ai/v1/sessions/$REBYTE_SESSION_ID \
  -H "Authorization: Bearer $REBYTE_API_KEY"

Deletion cancels an active turn before removing the Conversation.