Rebyte API v1

The Rebyte API separates reusable configuration from execution:

1. An Agent stores instructions, model, MCP servers, and skills.
2. Creating a Session takes a creation-time snapshot of that Agent and creates an isolated runtime. Updating the Agent later does not change existing Sessions.
3. A Message starts or queues work in the Session. Message submission returns 202 Accepted; execution continues asynchronously.

New integrations should use Agents, Sessions, and Messages. The older Tasks API remains available for compatibility, but it combines configuration, runtime creation, and the first prompt into one request.

Contract and base URL

Base URL:

https://api.rebyte.ai/v1

The complete /v1 contract is published from the service itself:

Format	URL	Authentication
OpenAPI 3.1 JSON	https://api.rebyte.ai/v1/openapi.json	None
LLM-friendly Markdown	https://api.rebyte.ai/v1/openapi.md	None

These documents are the canonical schema for the entire /v1 API, including request and response bodies, parameters, status codes, and security requirements. This page explains how to use that contract; use the published schema when generating a client or validating payloads.

Authentication and scopes

Send an organization API key in the API_KEY header. Get a key from Settings > API Keys.

curl https://api.rebyte.ai/v1/agents \
  -H "API_KEY: rbk_your_key_here"

The canonical header is API_KEY. Header names are case-insensitive; api-key and x-api-key are also accepted.

Scope	Access
tasks:read	Read Agents, Sessions, Messages, streams, legacy Tasks, Agent Computers, workspace artifacts, credits, and the Sandbox credential
tasks:write	Create/update/delete Agents and Sessions, submit/answer/interrupt Messages, mutate legacy Tasks and Agent Computers, and delete artifacts
files:write	Create file-upload URLs
webhooks:read	List and get webhook registrations
webhooks:write	Register and delete webhooks
accounts:write	Restricted partner account and top-up operations

The OpenAPI JSON and Markdown endpoints are public. All other endpoints require an API key; some advanced products also require a subscription, organization policy, or partner entitlement.

Quickstart

This example creates an Agent, snapshots it into a Session, submits a Message, and polls the authoritative Message resource. It requires curl and jq.

set -euo pipefail

export REBYTE_API_KEY='rbk_replace_me'
export REBYTE_BASE_URL='https://api.rebyte.ai'
RUN_KEY="$(date +%s)-$"

# 1. Create reusable configuration.
AGENT_JSON="$(
  curl -fsS -X POST "$REBYTE_BASE_URL/v1/agents" \
    -H "API_KEY: $REBYTE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Idempotency-Key: quickstart-agent-$RUN_KEY" \
    -d '{
      "name": "Research assistant",
      "instructions": "Answer clearly and cite the evidence you used."
    }'
)"
AGENT_ID="$(jq -er '.agent.id' <<<"$AGENT_JSON")"

# 2. Create an idle, isolated Session from an Agent snapshot.
SESSION_JSON="$(
  curl -fsS -X POST "$REBYTE_BASE_URL/v1/sessions" \
    -H "API_KEY: $REBYTE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Idempotency-Key: quickstart-session-$RUN_KEY" \
    -d "{\"agentId\":\"$AGENT_ID\",\"title\":\"Quickstart\"}"
)"
SESSION_ID="$(jq -er '.session.id' <<<"$SESSION_JSON")"

# 3. Submit work. Idempotency-Key is required for Messages.
ACCEPTED_JSON="$(
  curl -fsS -X POST "$REBYTE_BASE_URL/v1/sessions/$SESSION_ID/messages" \
    -H "API_KEY: $REBYTE_API_KEY" \
    -H 'Content-Type: application/json' \
    -H "Idempotency-Key: quickstart-message-$RUN_KEY" \
    -d '{"parts":[{"type":"text","text":"Reply with exactly: hello"}]}'
)"
MESSAGE_ID="$(jq -er '.message.id' <<<"$ACCEPTED_JSON")"
printf '%s\n' "$ACCEPTED_JSON" | jq .

# 4. GET is authoritative. Poll until terminal or paused for a HITL answer.
while :; do
  MESSAGE_JSON="$(
    curl -fsS "$REBYTE_BASE_URL/v1/sessions/$SESSION_ID/messages/$MESSAGE_ID" \
      -H "API_KEY: $REBYTE_API_KEY"
  )"
  STATUS="$(jq -r '.message.status' <<<"$MESSAGE_JSON")"
  case "$STATUS" in
    completed|failed|canceled|paused) break ;;
    *) sleep 1 ;;
  esac
done

printf '%s\n' "$MESSAGE_JSON" | jq .

Message submission returns only an acceptance projection:

{
  "message": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "object": "message",
    "sessionId": "660e8400-e29b-41d4-a716-446655440001",
    "status": "running",
    "warnings": []
  }
}

The acceptance status is running or queued. An idempotent replay can refer to work that has already advanced, so always use GET /v1/sessions/{sessionId}/messages/{messageId} for current state, final response, errors, and unresolved HITL actions.

Multiple submitted text parts are joined with newline characters into one effective prompt. Transcript reads return that normalized text as one part.

Agents

Agents are reusable configuration records; they do not execute by themselves.

Method	Endpoint	Scope	Purpose
POST	/v1/agents	tasks:write	Create an Agent
GET	/v1/agents	tasks:read	List organization Agents
GET	/v1/agents/{id}	tasks:read	Get an Agent
PATCH	/v1/agents/{id}	tasks:write	Update selected Agent fields
DELETE	/v1/agents/{id}	tasks:write	Delete an Agent when no Sessions still reference it

Create and update bodies can contain name, instructions, model, maxSteps, mcpServers, and skills. Skills use canonical GitHub owner/repo plus a repo-relative directory path. The OpenAPI schema contains the supported model IDs and MCP variants.

An Agent update affects only Sessions created afterward. Deleting an Agent is rejected while Sessions still reference it.

Sessions

A Session owns an isolated runtime and the durable transcript created from one Agent snapshot. Creating it is idle: execution starts with the first Message.

Method	Endpoint	Scope	Purpose
POST	/v1/sessions	tasks:write	Create an idle Session from agentId
GET	/v1/sessions	tasks:read	List Sessions; supports agentId, limit, and offset
GET	/v1/sessions/{id}	tasks:read	Read Session status and latest Message projection
GET	/v1/sessions/{id}/stream	tasks:read	Open the standing SSE stream
POST	/v1/sessions/{id}/interrupt	tasks:write	Interrupt the active turn without deleting the Session
DELETE	/v1/sessions/{id}	tasks:write	Cancel active work and delete the Session runtime

Session status is idle, running, or paused. latestMessageId and latestMessageStatus are convenient projections; read the Message itself for authoritative details.

Messages and transcript

Method	Endpoint	Scope	Purpose
POST	/v1/sessions/{id}/messages	tasks:write	Submit text parts asynchronously; returns 202
GET	/v1/sessions/{id}/messages	tasks:read	List the authoritative transcript with pagination
GET	/v1/sessions/{id}/messages/{messageId}	tasks:read	Get authoritative status, response, error, and pendingActions
POST	/v1/sessions/{id}/messages/{messageId}/answer	tasks:write	Answer one blocked HITL action

Durable Message statuses are queued, accepted, running, paused, completed, failed, and canceled. The public Message ID returned by POST is the same ID used in transcript URLs and SSE messageId; an SSE runId is a separate execution correlation ID.

Idempotency

Use Idempotency-Key for safe request retries. Keys are 1–255 visible ASCII characters.

Operation	Requirement	Replay behavior
Create Agent	Optional	Same key and definition returns the same Agent
Create Session	Optional	Same key and definition returns the same Session
Submit Message	Required	Same key and effective text returns the same public Message

Keys are scoped by organization and operation; Message keys are additionally scoped to the Session. Reusing a key with a different Agent or Session definition, or with different effective Message text, returns 409 idempotency_key_conflict.

Treat a timeout as an unknown outcome and retry the identical request with the identical key. Do not reuse a key for a different logical operation.

Standing Session SSE

Open one standing connection per Session:

curl -N "https://api.rebyte.ai/v1/sessions/$SESSION_ID/stream" \
  -H "API_KEY: $REBYTE_API_KEY"

The first frame is session.connected; heartbeat comments arrive every 15 seconds. The stream stays open across Messages and multiplexes conversation-level and per-run events.

Public event	Meaning
session.connected	Connection established with the current Session snapshot
session.event	Conversation-level runtime event
message.started	A public Message was attached to an execution run
message.event	Progress, output, tool, or HITL event
message.completed	Durable completed state
message.failed	Durable failed state
message.canceled	Durable canceled state
message.stream_end	End of that run channel, not the standing Session connection

SSE is a live/recent observation transport, not the authoritative event ledger:

• On connection, the service replays bounded recent history and follows active or recently updated runs. It follows at most 100 recent/active run channels.
• Per-channel history is capped at 2,000 events or 8 MiB; connection initialization buffers and socket backpressure are also bounded. The server closes the connection when a safety limit is exceeded.
• Reconnects can repeat recent events. Deduplicate using the complete SSE id value only within your consumer's observation window.
• The wire id is channel-scoped. Global ordering, durable Last-Event-ID replay, and an events cursor are not provided in v1.
• After a disconnect, missed tool/progress frames may be unrecoverable. Reconnect with backoff, then reconcile through GET /messages or GET /messages/{messageId}.

Message GETs are authoritative for status, unresolved HITL actions, final response, and error. A message.stream_end frame is not proof of completion; wait for a durable terminal event or confirm with GET.

Human-in-the-loop questions

When an Agent needs input, the Message becomes paused. SSE emits a message.event whose nested data.sourceType is tool_ask_user_question, with normalized data.actionId and data.question.

The same unresolved action survives disconnects in the authoritative Message:

{
  "message": {
    "id": "message-uuid",
    "status": "paused",
    "pendingActions": [
      {
        "type": "ask_user_question",
        "actionId": 42,
        "messageId": "message-uuid",
        "question": {
          "question": "Which environment?",
          "options": [
            {"label": "Staging", "description": null},
            {"label": "Production", "description": null}
          ],
          "multiSelect": false,
          "questions": [
            {
              "question": "Which environment?",
              "options": [
                {"label": "Staging", "description": null},
                {"label": "Production", "description": null}
              ],
              "multiSelect": false
            }
          ]
        }
      }
    ]
  }
}

Answer using the action's canonical messageId and actionId:

curl -fsS -X POST \
  "$REBYTE_BASE_URL/v1/sessions/$SESSION_ID/messages/$MESSAGE_ID/answer" \
  -H "API_KEY: $REBYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"actionId":42,"answer":"Staging"}'

answer may be any JSON object, array, string, number, boolean, or null. A response status of resuming means the turn resumed; accepted means the answer was recorded while another blocked action remains. Stale, mismatched, duplicate, or already-resolved actions return 409. Submitting a new Message while the Session is paused returns 409 session_paused; answer the pending action first.

Webhooks

Organization webhook registrations remain available at /v1/webhooks. They receive task lifecycle events only for legacy API tasks (source = api) and new Agent API Sessions (source = agent_api). Web UI tasks and other sources are not delivered through this public webhook path.

Webhook event names remain task.created, task.running, task.completed, task.failed, and task.canceled. For a new Session-origin event, the payload's taskId identifies the underlying public Session.

Delivery is deliberately best-effort:

• Each matching event gets one HTTP attempt with a 10-second timeout.
• There is no automatic retry, delivery queue, or durable delivery ledger.
• A timeout, network error, or non-2xx response may be dropped permanently.
• Delivery never blocks or fails Agent execution.

Use webhook delivery as a wake-up signal, then reconcile with Session and Message GETs. See Outbound Webhooks for registration and signature verification.

Legacy and advanced endpoint index

The OpenAPI document is the complete contract. This index helps locate compatible and advanced endpoint families; it does not replace their schemas.

Legacy Tasks

The Tasks API remains compatible for existing integrations. New integrations should prefer Agent → Session → Message.

Method	Endpoint
POST, GET	/v1/tasks
GET, DELETE	/v1/tasks/{id}
GET	/v1/tasks/{id}/content
POST	/v1/tasks/{id}/prompts
PATCH	/v1/tasks/{id}/visibility
GET	/v1/tasks/{id}/events
GET	/v1/tasks/{id}/prompts/{promptId}/events
POST	/v1/tasks/{id}/cancel
POST	/v1/tasks/{id}/answer

Files

Method	Endpoint	Scope
POST	/v1/files	files:write

Creates a signed upload URL for inputs used by compatible APIs.

Webhooks

Method	Endpoint	Scope
POST	/v1/webhooks	webhooks:write
GET	/v1/webhooks	webhooks:read
GET	/v1/webhooks/{id}	webhooks:read
DELETE	/v1/webhooks/{id}	webhooks:write

Agent Computers

These endpoints expose persistent workspace/VM management and are separate from reusable /v1/agents configuration.

Method	Endpoint
POST, GET	/v1/agent-computers
GET, PATCH	/v1/agent-computers/{id}
POST	/v1/agent-computers/{id}/db9/api-key
POST	/v1/agent-computers/{id}/db9/share-token

See Agent Computers API.

Workspaces and artifacts

The public Workspace surface is output-only. It has actual GET and DELETE operations only; there is no /v1/workspaces create endpoint and no artifact upload endpoint.

Method	Endpoint
GET	/v1/workspaces/{id}/artifacts
GET	/v1/workspaces/{id}/artifacts/{filename}
DELETE	/v1/workspaces/{id}/artifacts/{filename}
DELETE	/v1/workspaces/{id}/artifacts

Context Lake

Context Lake requires a Pro subscription.

Method	Endpoint
GET, PATCH	/v1/context-lake/config
GET, POST	/v1/context-lake/datasets
PUT, DELETE	/v1/context-lake/datasets/{name}
GET, POST	/v1/context-lake/views
PUT, DELETE	/v1/context-lake/views/{name}
POST	/v1/context-lake/sql
GET	/v1/context-lake/status
POST	/v1/context-lake/start
POST	/v1/context-lake/stop
POST	/v1/context-lake/redeploy

See Agent Context API.

Billing

Method	Endpoint	Access
GET	/v1/billing/credits	tasks:read
POST	/v1/billing/topups	Restricted partner key with accounts:write

Restricted Partner accounts

These are not general application endpoints. They require partner provisioning and an accounts:write key; ownership rules apply to linked accounts.

Method	Endpoint
POST, GET	/v1/accounts
PATCH	/v1/accounts/{id}/billing
POST	/v1/billing/topups

Sandbox

Method	Endpoint	Scope
GET	/v1/sandbox/api-key	tasks:read

This returns the organization-scoped Microsandbox gateway URL and credential for direct SDK use. Treat the returned key as a secret.

Errors

New Agent and Session endpoints use a structured error envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": []
  }
}

Common new-contract codes include missing_api_key, invalid_api_key, insufficient_scopes, validation_error, not_found, agent_not_found, missing_idempotency_key, idempotency_key_conflict, session_paused, session_unavailable, no_blocked_action, paid_model_required, and internal_error. The HTTP status and exact schema for each operation are defined in OpenAPI.

Some legacy and advanced endpoint families predate the new contract and may return a different error body, such as { "error": "message" }, or additional fields. Do not assume every old endpoint shares the Agent/Session error envelope; follow that operation's OpenAPI response schema.

Deferred from v1

The first version does not include a Rebyte CLI, ACP adapter, or durable events cursor. SSE frame IDs are transport identifiers, not the deferred cursor API. Those surfaces can be added later without changing the Agent, Session, Message, or authoritative transcript model.