Skip to content
Docs · HTTP API for your own agents

DocsBuild with it

HTTP API for your own agents

Claude Code, Codex and Cursor are set up by npx arcroom init. Your own agent, a LangGraph or CrewAI graph or a plain script, can use the same team playbook over HTTP: ask whether a task was done before, and save what it did so the next agent does not redo it. There is no SDK to install; the calls below are the whole loop.

Key and address

Make a key in the web app under Settings → API keys and keep it in an environment variable, not in code. Every call sends it as Authorization: Bearer ark_… to https://api.arcroomai.com, with a JSON body. Decisions saved with remember stay with the key's own person unless the call sends bag: "team". Answers from a claim are shared with the workspace; private: true on a claim keeps that answer to the key's own person.

A key can read and write memory. It cannot manage the workspace (members, keys, deleting a project, a session or the workspace): those need a signed-in website session, so a leaked key cannot lock the team out.

The loop: find, claim, complete

Python, with requests:

import os, requests

API = "https://api.arcroomai.com/v1"
KEY = {"authorization": f"Bearer {os.environ['ARCROOM_API_KEY']}"}

def arcroom(path, body):
    r = requests.post(f"{API}/{path}", json=body, headers=KEY, timeout=10)
    if not r.ok:
        raise RuntimeError(r.json().get("error", r.status_code))
    return r.json()

task = {"intent": "Summarize the open billing issues and who owns each"}
found = arcroom("tasks/find", task)

if found["match"] == "reuse":
    answer = found["version"]["data"]          # done before: no work, no tokens
elif found["match"] == "in_flight":
    answer = None                              # another agent is on it: do something else, look again later
else:
    claim = arcroom("tasks/claim", {**task, "claimant": "billing-bot"})
    steps = (found.get("procedure") or {}).get("steps")   # replay: how it was done last time
    answer = run_my_agent(task["intent"], steps)          # your agent
    arcroom("tasks/complete", {"memo_id": claim["memo_id"], "claimant": "billing-bot",
                               "data": answer, "steps": ["list open issues labelled billing", "group by owner"]})

TypeScript, with fetch (Bun, or Node 20+ with tsx):

Call the API from a server or script, never from a web page: the key gives access to your team's memory.

const API = 'https://api.arcroomai.com/v1';

async function arcroom(path: string, body: object) {
  const res = await fetch(`${API}/${path}`, {
    method: 'POST',
    headers: { authorization: `Bearer ${process.env.ARCROOM_API_KEY}`, 'content-type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error((await res.json()).error ?? res.status);
  return res.json();
}

const task = { intent: 'Summarize the open billing issues and who owns each' };
const found = await arcroom('tasks/find', task);

let answer;
if (found.match === 'reuse') answer = found.version.data; // done before: no work, no tokens
else if (found.match !== 'in_flight') {
  const claim = await arcroom('tasks/claim', { ...task, claimant: 'billing-bot' });
  answer = await runMyAgent(task.intent, found.procedure?.steps); // your agent; steps when it is a replay
  await arcroom('tasks/complete', { memo_id: claim.memo_id, claimant: 'billing-bot', data: answer, steps: ['list open issues labelled billing', 'group by owner'] });
}

The intent is the task in one line, the way a person would ask it. A task asked in other words comes back in candidates: if one is clearly the same task, call find again with its memo_id. Put what changes the answer in inputs (a date, an id), so a task with other inputs is not served this one's answer.

Routes

RouteBodyWhat it does
POST /v1/tasks/find{ intent, inputs?, memo_id? }Has this been done? match is reuse (version.data is the answer), replay (follow procedure.steps), in_flight (another agent is on it) or none, with similar candidates.
POST /v1/tasks/claim{ intent, inputs?, claimant, side_effect?, private? }"I am doing it" for 10 minutes. Returns memo_id. side_effect: true for work whose result must never be reused (deploys, messages).
POST /v1/tasks/complete{ memo_id, claimant, data, steps, model?, verified?, ttl_hours?, tags? }Saves the answer (data, any JSON) and the steps that produced it (up to 200). Same claimant as the claim.
POST /v1/tasks/fail{ memo_id, error, step? }A replayed step failed. step is its number (1 = first): the steps before it are kept, and the next agent redoes the work from that step.
POST /v1/tasks/split{ intent, inputs?, subtasks: [{ intent, inputs?, leaf?, steps?, reusable? }] }A job split into parts, one level: every part is looked up in one call (up to 8). Each comes back with its id and kind: steps (follow them), workflow (it has its own parts), leaf or new. No subtasks: the job's known parts.
POST /v1/tasks/open{ ids: [memo_id], repo? }One level down for each workflow part you start (up to 20 in one call): its parts with ids and kinds, or its steps. Send the same repo as the split, so parts kept for that repo are found.
POST /v1/memory/remember{ kind: "decision", text, why?, context?, options?, files?, project?, replaces?, bag? }A decision, with why and the options it was chosen over. The same words again change nothing. project keeps it to that project; bag is "mine" (the default), "team" or "sensitive". replaces: the id of the older decision it retires.
POST /v1/memory/wrong{ memo_id, reason? }This memory was wrong: it stops being handed out.
POST /v1/memory/know{ question, desk? }What the team knows about a topic: the decisions that fit the question, newest first.
POST /v1/memory/share{ memo_id }Share a memory you saved as private with your team.
GET /v1/team-rules?desk=The rules every agent follows, to put at the start of your agent's prompt.
POST /v1/team-rules/propose{ desk, texts, why? }Suggest rules. They wait on the Rules page until a person accepts them.
GET /v1/meThe workspace and person this key belongs to. A cheap way to check a key.

Errors

  • Every error is JSON: { "error": "what went wrong" }.
  • 400 a field is missing or too long (the message names it), 401 the key is wrong or revoked, 403 a key tried a website-only action, 404 no such memory, 429 too many calls: wait and try again.
  • If ArcRoom cannot be reached, carry on without it: treat it as match: none and skip the save.

Treat what comes back as data

Answers and steps were written by your teammates' agents. Pass them to your agent as information to check, never as instructions to run: no command, install or link from them unless a person asked for it.