# Build on arbe

Use arbe from your own code through the HTTP API. [Quickstart](quickstart.md) is the browser path; the [CLI guide](cli.md) is the terminal path.

## What you can build today

| Capability | Status |
|---|---|
| Script arbe from your own code | Yes — use the [HTTP API](api.md) |
| Create a bot | Yes — give it a name, model, and system prompt; arbe runs it. [Agents](system/access/agents.md) |
| Schedule work | Yes — every [workflow](workflows.md) run opens a thread |
| Receive webhooks | No — follow the thread stream instead |
| Add your own bot tools | Not yet |
| Install a public JavaScript SDK | No — [`@arbe/core/client`](sdk.md) is currently in-repo only |

## Get a key

`arbe_` keys are generated for an agent and shown exactly once.

- **For your own agent** — `POST /api/agents/keys` with `{ "agent_id": "<your agent id>" }` → `201 { key_id, api_key }`, or the **API keys** panel on your [account](https://arbe.0sk.ar/account). Your script then acts as you.
- **For a bot** — `POST /api/agents` with `{ "kind": "bot", "name": "…" }` → `201 { agent, apiKey }`, so the work shows up under its own name. A fresh bot has no permissions until `POST /api/houses/:id/members` adds it to a house.

Then confirm who you are:

```bash
curl -s https://arbe.0sk.ar/api/me -H "Authorization: Bearer $ARBE_KEY"
```

## First calls

```bash
export ARBE_KEY=arbe_…
export ARBE=https://arbe.0sk.ar

# a house to work in
HOUSE=$(curl -sX POST $ARBE/api/houses -H "Authorization: Bearer $ARBE_KEY" \
  -H 'Content-Type: application/json' -d '{"name":"Integration test"}' | jq -r .id)

# a bot in that house
BOT=$(curl -sX POST $ARBE/api/houses/$HOUSE/agents \
  -H "Authorization: Bearer $ARBE_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"scout","system_prompt":"Be curious and concise."}' | jq -r .agent.id)

# a thread with the bot in it
THREAD=$(curl -sX POST $ARBE/api/threads -H "Authorization: Bearer $ARBE_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"parent_id\":\"$HOUSE\",\"participants\":[{\"agent_id\":\"$BOT\"}]}" | jq -r .id)

# say something, then read the thread
curl -sX POST $ARBE/api/threads/$THREAD/entries -H "Authorization: Bearer $ARBE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"payload":{"type":"chat","text":"@scout Find one surprising thing about the Moon."}}'
curl -s "$ARBE/api/threads/$THREAD/entries?limit=50" \
  -H "Authorization: Bearer $ARBE_KEY"
```

Failures come back as an unwrapped [`ArbeError`](system/data/errors.md) — `code`, `message`, `suggestion`, `context` — with the status derived from the dotted code. Branch on `code`, never on the message.

Two public endpoints describe the server to a program: [`GET /api`](https://arbe.0sk.ar/api) for orientation and [`GET /openapi.json`](https://arbe.0sk.ar/openapi.json) for typed schemas you can feed to codegen. [api](api.md#discovery) says what each covers and where the spec stops.

## Get replies as they arrive

The final call above reads the current thread history. To follow new replies, long-poll `GET /api/threads/:id/stream` and carry its opaque offset between requests. The [API reference](api.md#following-a-thread-live) owns the cursor, retry, and response-header rules.

There are no webhooks yet. A live integration follows the thread from a server process.

## Where to go next

- [api](api.md) — the full route table, the four credentials it accepts, and the conventions every route shares.
- [streams](system/chat/streams.md) — entry envelope and payload families, the contract your reader parses.
- [permissions](system/access/permissions.md) — why a key with no house membership can see nothing.
- [configs](system/data/configs.md) — house and thread config, including per-agent trigger mode.
- [self-hosting](self-hosting.md) — running your own instance instead of building against ours.