---
name: alphabook
version: 1.0.0
description: Agent-facing research access for AlphaBook's corpus and retrieval runtime.
homepage: https://alpha-book.org
metadata: {"alphabook":{"api_base":"https://api.alpha-book.org/v1","category":"research"}}
---

# AlphaBook

You are the AI agent that should connect to AlphaBook over the CLI.

## What to do

1. Register yourself.
2. Save the returned `api_key`.
3. Use the same API key for future requests.

## Register first

Registration is unauthenticated. Save the returned `api_key` and use it as a Bearer token on future requests.

```bash
curl -X POST https://api.alpha-book.org/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name":"YourAgentName","description":"What you research"}'
```

## Check your identity

```bash
curl https://api.alpha-book.org/v1/agents/me \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Run research from the CLI

```bash
curl -X POST https://api.alpha-book.org/v1/research/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Find passages about grief and loss in Jane Eyre and Great Expectations, with citations."}'
```

The response includes a `runId`, `sessionId`, and polling URLs.

## Poll until completion

```bash
curl https://api.alpha-book.org/v1/research/runs/RUN_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When the run finishes, read `result.answer`, `result.citations`, and `result.hits` from the JSON response.

## Inspect logs if needed

```bash
curl https://api.alpha-book.org/v1/research/runs/RUN_ID/logs \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Useful endpoints

- `POST https://api.alpha-book.org/v1/research/runs` starts an autonomous agentic research run
- `GET https://api.alpha-book.org/v1/research/runs/:runId` returns run status and the final research result
- `GET https://api.alpha-book.org/v1/research/runs/:runId/logs` returns the full transcript and artifacts
- `GET https://api.alpha-book.org/v1/sessions` lists your sessions
- `GET https://api.alpha-book.org/v1/sessions/:sessionId/runs` lists runs for a session
- `GET https://api.alpha-book.org/v1/sessions/:sessionId/runs/:runId` returns run status, tool trace, and artifacts
- `GET https://api.alpha-book.org/v1/sessions/:sessionId/messages` returns the transcript
- `GET https://api.alpha-book.org/v1/agents/me` returns your agent identity

## Auth

Use `Authorization: Bearer YOUR_API_KEY` on every CLI request.

## Billing

If AlphaBook replies with HTTP 402, inspect the JSON body plus the `PAYMENT-REQUIRED` or `payment-required` headers for x402 requirements.
When you pay, retry the same request with `PAYMENT-SIGNATURE` and read `PAYMENT-RESPONSE` on success.