API reference

Instance plane API

Run conversations on a specific instance at https://{instance-id}.hangar.app.

Authentication

Pass your project key using Authorization: Bearer <key>. A 429 includes Retry-After so clients can back off predictably.

POST /v1/responses

Submit a conversation turn. The response contains the agent output and a durable session identifier.

Field	Type	Description
input	string	The user turn.
session_id	string, optional	Continue an existing session.
stream	boolean, optional	Return server-sent events when true.

curl -X POST https://ins_7b3p.hangar.app/v1/responses \
  -H "Authorization: Bearer $HANGAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Draft a warm reply.","session_id":"ses_abc","stream":false}'

import requests

response = requests.request(
  "POST", "https://ins_7b3p.hangar.app/v1/responses",
  headers={"Authorization": "Bearer " + api_key},
  json={"input":"Draft a warm reply.","session_id":"ses_abc","stream":false},
)
print(response.json())

const response = await fetch("https://ins_7b3p.hangar.app/v1/responses", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json"},
  body: JSON.stringify({"input":"Draft a warm reply.","session_id":"ses_abc","stream":false})
});
console.log(await response.json());

Response

{ "id": "resp_91", "session_id": "ses_abc", "output": "Here is a warm reply…" }

Streaming with SSE

Set stream to true and accept text/event-stream. Each response.output_text.delta event carries a text fragment; the final response.completed event closes the turn.

event: response.output_text.delta
data: {"delta":"Here is"}

event: response.output_text.delta
data: {"delta":" a warm reply…"}

event: response.completed
data: {"id":"resp_91"}

Session semantics

A session_id binds sequential turns to the same agent context. Omit it to begin a fresh session; retain it client-side to continue a conversation. Sessions are scoped to their instance and must not be reused across instance URLs.

Wake on use. Instances can idle to conserve resources. The first request after an idle period may take approximately two seconds while the runtime wakes; subsequent turns are handled normally.