JohnnyOne Partner API

Two transports

Your account is a dedicated service account (one tenant + user). JohnnyOne hosts the desktop runtime for you — you never install anything. The server resolves your desktop node from your token; you never supply a node id.

Authentication

Log in once to get a short-lived accessToken (JWT) and a longer-lived refreshToken. Send the access token on every GraphQL request and on the WebSocket upgrade.

curl -s https://johnnyone.ethan-353.workers.dev/graphql \
  -H 'content-type: application/json' \
  -H 'x-tenant-id: your-tenant' \
  -d '{"query":"mutation($i:LoginInput!){login(input:$i){accessToken refreshToken}}",
       "variables":{"i":{"email":"you@partner.com","password":"…","tenantId":"your-tenant"}}}'

Use the token as a Bearer header on GraphQL:

Authorization: Bearer <accessToken>

GraphQL API

Endpoint: POST https://johnnyone.ethan-353.workers.dev/graphql. The schema is introspectable — point a GraphQL client at it to discover every type and argument. The partner-usable operations are below.

Terminal / AI sessions

CreateAiSessionInput: { title?, provider?, model?, workingDirectory? }. The returned AiSession.id is the sessionId you use on the WebSocket.

listAiMessages returns messages for a session (use with listAiSessions / getAiSession).

curl -s https://johnnyone.ethan-353.workers.dev/graphql \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"query":"mutation($i:CreateAiSessionInput!){createAiSession(input:$i){id title provider workingDirectory}}",
       "variables":{"i":{"provider":"claude_code","workingDirectory":"/home/you/project"}}}'

Planner / development runs

CreateAgentPlanInput: { runType?, title?, workspacePath!, planPath!, workerProvider!, reviewerProvider!, brief?, appScope?, docsScope?, referencePaths? }. getAgentPlan returns an AgentPlanRun with plan, phases, tasks, and events — poll it (or watch agent_plan_run_updated on the WebSocket) to track progress.

Discovery helpers

listDesktopNodes (your online desktop node) · listDetectedCliTools (available providers/CLIs on your host).

Live terminal (WebSocket)

Connect to wss://johnnyone.ethan-353.workers.dev/api/relay/ws with your token. The server validates the token, resolves your desktop node, and routes the socket. Messages are JSON envelopes:

{ "type": "<envelope type>", "sessionId": "<AiSession.id>", "data": <payload> }

Client → server

Server → client

Quickstart (Node.js)

Login → create a session → stream its terminal → send a command. Requires ws (and Node 18+ for fetch).

import WebSocket from 'ws';
const BASE = 'https://johnnyone.ethan-353.workers.dev';
const gql = (q, variables, token) => fetch(BASE + '/graphql', {
  method: 'POST',
  headers: { 'content-type': 'application/json', ...(token && { authorization: `Bearer ${token}` }) },
  body: JSON.stringify({ query: q, variables }),
}).then(r => r.json());

// 1. Login
const { data: { login } } = await gql(
  'mutation($i:LoginInput!){login(input:$i){accessToken refreshToken}}',
  { i: { email: 'you@partner.com', password: process.env.PW, tenantId: 'your-tenant' } });
const token = login.accessToken;

// 2. Create a session
const { data: { createAiSession: s } } = await gql(
  'mutation($i:CreateAiSessionInput!){createAiSession(input:$i){id}}',
  { i: { provider: 'claude_code', workingDirectory: '/home/you/project' } }, token);

// 3. Open the live terminal
const ws = new WebSocket(`${BASE.replace('https','wss')}/api/relay/ws`, {
  headers: { authorization: `Bearer ${token}` },   // or append ?token= in the URL
});
ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'terminal_visual_subscribe', sessionId: s.id }));
  ws.send(JSON.stringify({ type: 'terminal_command', sessionId: s.id, data: 'echo hello\r' }));
});
ws.on('message', (buf) => {
  const msg = JSON.parse(buf.toString());
  if (msg.type === 'terminal_screen') console.log(msg.data);
});

A Python equivalent uses httpx/urllib for GraphQL and websockets for the socket — same envelopes.

Errors & limits

• WebSocket upgrade rejected: 401 = missing/invalid token; 503 = no online desktop node for your account. Retry after re-authenticating / once the host is online.
• GraphQL errors come back in the standard errors[] array (e.g. Authentication required for a missing/expired token).
• Foreign session: an envelope or query for a session you don't own is rejected with error code forbidden_session.
• Token expiry mid-socket: the socket authenticates once at upgrade. When the access token nears expiry, refresh it and reconnect; re-subscribe after reconnect. Build in reconnect-with-backoff.

Versioning & forward-compat

The endpoint is unversioned and additive. Select only the fields you need; tolerate unknown enum values and extra response fields.

For errors use the real signals: GraphQL errors[].message text, WSS upgrade HTTP status 401/503, and in terminal_command_ack the .error:'forbidden_session' field. (The published contract does not emit extensions.code values such as UNAUTHENTICATED/FORBIDDEN_SCOPE/RATE_LIMITED.)

Changelog

• 2026-06-18 — v1 initial public surface: AI-session lifecycle + AgentPlan GraphQL CRUD; live terminal I/O over WSS relay envelopes; JWT + ?token= auth; server-side node resolution; session ownership gate; minimal Node.js + Python example clients; public docs site on CF Pages at https://johnnyone-partner-api.pages.dev.

Full policy: see the inlined summary above and the runbook (deployed alongside). All changes additive unless removal sweep with deprecation.

For AI agents

• GraphQL is introspectable — run a standard introspection query against /graphql to get the full typed schema; you don't need to hardcode the operations above.
• The WebSocket protocol is the only non-introspectable part — the envelope tables in Live terminal are the complete contract.
• Start from the Quickstart — it's the full happy path (login → session → subscribe → command → read screen) in ~25 lines.
• Identity is server-resolved — authenticate with the token only; never send a node id.

JohnnyOne Partner API · integration guide. Operations and envelopes reflect the live GraphQL schema (worker/schema/*.graphql) and relay protocol.