API Reference - Sessions

import httpx
r = httpx.post(
    "https://primer.example/v1/workspaces/ws-prod/sessions",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "binding": {"kind": "agent", "agent_id": "agent-coder"},
        "auto_start": True,
        "initial_instructions": "Implement the described feature",
    },
)
r.raise_for_status()
session = r.json()

const r = await fetch("/v1/workspaces/ws-prod/sessions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    binding: { kind: "agent", agent_id: "agent-coder" },
    auto_start: true,
    initial_instructions: "Implement the described feature",
  }),
});
const session = await r.json();

import httpx
r = httpx.get(
    "https://primer.example/v1/sessions",
    headers={"Authorization": f"Bearer {token}"},
    params={"workspace_id": "ws-prod", "status": "running", "limit": 20, "offset": 0},
)
r.raise_for_status()
page = r.json()

const params = new URLSearchParams({
  workspace_id: "ws-prod", status: "running", limit: 20, offset: 0,
});
const r = await fetch(`/v1/sessions?${params}`, {
  headers: { "Authorization": `Bearer ${token}` },
});
const page = await r.json();

import httpx
r = httpx.get(
    "https://primer.example/v1/sessions/sess-abc123",
    headers={"Authorization": f"Bearer {token}"},
)
r.raise_for_status()
session = r.json()

const r = await fetch("/v1/sessions/sess-abc123", {
  headers: { "Authorization": `Bearer ${token}` },
});
const session = await r.json();

import httpx
r = httpx.get(
    "https://primer.example/v1/sessions/sess-abc123/messages",
    headers={"Authorization": f"Bearer {token}"},
    params={"limit": 200, "offset": 0},
)
r.raise_for_status()
page = r.json()

const params = new URLSearchParams({ limit: 200, offset: 0 });
const r = await fetch(`/v1/sessions/sess-abc123/messages?${params}`, {
  headers: { "Authorization": `Bearer ${token}` },
});
const page = await r.json();

import httpx
r = httpx.post(
    "https://primer.example/v1/sessions/find",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "predicate": {
            "kind": "predicate",
            "op": "=",
            "left": {"kind": "field", "name": "workspace_id"},
            "right": {"kind": "value", "value": "ws-prod"},
        },
        "page": {"kind": "offset", "offset": 0, "length": 25},
        "order_by": [{"field": "created_at", "direction": "desc"}],
    },
)
r.raise_for_status()
result = r.json()

const r = await fetch("/v1/sessions/find", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    predicate: {
      kind: "predicate", op: "=",
      left: { kind: "field", name: "workspace_id" },
      right: { kind: "value", value: "ws-prod" },
    },
    page: { kind: "offset", offset: 0, length: 25 },
    order_by: [{ field: "created_at", direction: "desc" }],
  }),
});
const result = await r.json();

import httpx
r = httpx.post(
    "https://primer.example/v1/workspaces/ws-prod/sessions/sess-abc123/cancel",
    headers={"Authorization": f"Bearer {token}"},
)
r.raise_for_status()
session = r.json()

const r = await fetch(
  "/v1/workspaces/ws-prod/sessions/sess-abc123/cancel",
  { method: "POST", headers: { "Authorization": `Bearer ${token}` } },
);
const session = await r.json();

import httpx
r = httpx.get(
    "https://primer.example/v1/sessions/sess-abc123/ask_user/pending",
    headers={"Authorization": f"Bearer {token}"},
)

const r = await fetch("/v1/sessions/sess-abc123/ask_user/pending", {
  headers: { "Authorization": `Bearer ${token}` },
});

import httpx
r = httpx.post(
    "https://primer.example/v1/sessions/sess-abc123/ask_user/respond",
    headers={"Authorization": f"Bearer {token}"},
    json={"tool_call_id": "tc-001", "response": "Use the OAuth2 flow"},
)
r.raise_for_status()

const r = await fetch("/v1/sessions/sess-abc123/ask_user/respond", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ tool_call_id: "tc-001", response: "Use the OAuth2 flow" }),
});

import httpx
r = httpx.get(
    "https://primer.example/v1/sessions/sess-abc123/tool_approval/pending",
    headers={"Authorization": f"Bearer {token}"},
)

const r = await fetch("/v1/sessions/sess-abc123/tool_approval/pending", {
  headers: { "Authorization": `Bearer ${token}` },
});

import httpx
r = httpx.post(
    "https://primer.example/v1/sessions/sess-abc123/tool_approval/respond",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "tool_call_id": "tc-shell-001",
        "decision": "approved",
        "reason": "operator confirmed",
    },
)
r.raise_for_status()

const r = await fetch("/v1/sessions/sess-abc123/tool_approval/respond", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tool_call_id: "tc-shell-001",
    decision: "approved",
    reason: "operator confirmed",
  }),
});

# Catch via r.raise_for_status() or inspect r.json()["type"]:
# "/errors/not-found"        : resource does not exist
# "/errors/conflict"         : illegal state transition (e.g. resume on ended)
# "/errors/validation-error" : request body failed schema validation

// On error, r.ok === false and r.json() returns:
// { type: "/errors/not-found", title: "...", status: 404, detail: "..." }
// Common types: /errors/not-found, /errors/conflict, /errors/validation-error