Re-attach to a turn’s stream

Part of Gateway, 7 operations. The overview covers keys, scopes and errors.

GET /v1/turns/{session}/stream

Server-sent events: every journaled frame of the turn after after (or Last-Event-ID), then the live frames until its answer or error. A cursor past the journal gets one resync with the text so far. Needs the turns:read scope.

A caller key holding turns:read (Authorization: Bearer sbc_… or x-api-key: sbc_…), or a signed-in session.

Operation id streamTurn in Gateway.

Path parameters

session string required
The conversation id (what x-superbot-session named, or the session of an async call’s 202).

Query parameters

request string required
The turn’s request id (required).
after string optional
The last frame id already seen.

Response 200

The turn’s frames as server-sent events.

text/event-stream: string.

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`. No key yet: create one at /account/api, or sign a user in at /auth.md.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.

view .md openapi

Request

curl

curl -sS -X GET "https://superbot.gg/v1/turns/$SESSION/stream?request=string" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const session = 'SESSION';
const res = await fetch(`https://superbot.gg/v1/turns/${session}/stream?request=string`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

session = "SESSION"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/turns/{session}/stream?request=string",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The turn’s frames as server-sent events.

text/event-stream: string

401 The bearer is missing, malformed or unknown.

{
  "error": "unauthorized",
  "message": "Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.",
  "doc_url": "https://superbot.gg/developers#errors-unauthorized",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

403 The key lacks a scope (insufficient_scope), is revoked, or may not call this route.

{
  "error": "insufficient_scope",
  "message": "The key lacks the scope in required_scopes; mint a key that holds it.",
  "doc_url": "https://superbot.gg/developers#errors-insufficient_scope",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}