#For AI agents

1. POST /v1/streams                       -> id, rtmp_url, stream_key, whip_url, embed_url
   (send an Idempotency-Key so a retried call can't create two streams)
2. Give the publisher rtmp_url + stream_key (OBS), or whip_url (browser),
   or run ffmpeg yourself (see the Quickstart).
   Give viewers embed_url. Nothing else is needed to watch.
3. GET /v1/streams/{id} every 5 s until status is "live".
   While live, read ingest.limit_warning and ingest.keyframe_warning and tell the
   publisher what to fix. Stop polling when status is ended, expired or cancelled.
4. DELETE /v1/streams/{id} to end it.
   Later: GET /v1/streams/{id} shows recording.status = "ready";
   POST /v1/streams/{id}/recording/download returns a link to the MP4.

[
  {
    "name": "create_live_stream",
    "description": "Create a JustOnAir live stream. Returns where to send video (rtmp_url + stream_key for OBS/ffmpeg, whip_url for a browser) and where to watch (embed_url, a player page anyone can open). The stream waits 30 minutes for video.",
    "input_schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string", "description": "Title viewers see on the player. Up to 100 characters." },
        "max_resolution": { "type": "integer", "enum": [480, 720, 1080], "description": "Tallest video the publisher will send. Default 720." },
        "record": { "type": "boolean", "description": "Make an MP4 after the stream ends. Default true." }
      }
    }
  },
  {
    "name": "get_live_stream",
    "description": "Status of a stream: pending, live, ended, expired or cancelled; what is arriving (ingest) with any warnings; how many viewers are watching (viewers.now) and the peak; cost so far; and the recording once it ends.",
    "input_schema": {
      "type": "object",
      "properties": { "id": { "type": "string", "description": "Stream id, str_..." } },
      "required": ["id"]
    }
  },
  {
    "name": "end_live_stream",
    "description": "End a live stream now (the publisher is disconnected, viewers see the end screen) or cancel one that hasn't started.",
    "input_schema": {
      "type": "object",
      "properties": { "id": { "type": "string", "description": "Stream id, str_..." } },
      "required": ["id"]
    }
  }
]

const API = 'https://api.justonair.com';
const headers = { Authorization: `Bearer ${process.env.JOA_API_KEY}`, 'Content-Type': 'application/json' };

async function call(method: string, path: string, body?: unknown, extra: Record<string, string> = {}) {
  const res = await fetch(API + path, { method, headers: { ...headers, ...extra }, body: body ? JSON.stringify(body) : undefined });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); // codes: docs.justonair.com/errors
  return data;
}

export const tools = {
  create_live_stream: (input: { name?: string; max_resolution?: number; record?: boolean }) =>
    call('POST', '/v1/streams', input, { 'Idempotency-Key': crypto.randomUUID() }),
  get_live_stream: ({ id }: { id: string }) => call('GET', `/v1/streams/${encodeURIComponent(id)}`),
  end_live_stream: ({ id }: { id: string }) => call('DELETE', `/v1/streams/${encodeURIComponent(id)}`),
};

To start a live stream, use the JustOnAir API (docs: https://docs.justonair.com/llms.txt).
Call create_live_stream right before the broadcast, not in advance: a stream expires
after 30 minutes without video. Send the publisher rtmp_url and stream_key privately
(OBS: Settings > Stream > Custom; keyframe interval 2 s). Give viewers embed_url.
Check get_live_stream until status is "live" and report any ingest warning.
Call end_live_stream when the user says the broadcast is over.
Never reveal stream_key or whip_url to anyone but the publisher.