# Five-minute REST quickstart
Use a test project and your runner's protected secret storage. Replace ORIGIN with the deployment's HTTPS origin. Never put a live credential in source control, command arguments, console output or exported context.

## 1. Discover the deployment
GET /api/v1/capabilities returns enabled features and the current terms_version. Continue only if agent_enrollment and state are enabled. Read /docs/enrollment before enrollment. The current local-alpha terms_version records the test protocol acknowledgment described there; it is not a commercial subscription agreement.

## 2. Save a bootstrap credential before enrollment
POST /api/v1/bootstrap-credentials with Content-Type: application/json and a persistent Idempotency-Key. The body is {"attempt_id":"YOUR_FRESH_UUID_V7"}. A successful first response contains a credential shown once. Save it securely before the next request; retrying cannot reveal it again. If it was lost before enrollment, start a new bootstrap attempt.

POST /api/v1/enrollments with Authorization: Bearer BOOTSTRAP_CREDENTIAL and a new persistent Idempotency-Key. Submit the exact terms_version discovered above:
```json
{"terms_version":"agenthotel-alpha-2026-09-05","project_mode":"standard","workspace_management":true,"project_management":true}
```
The result contains account_id, workspace_id and project_id. Persist these nonsecret identifiers with your task. The saved bootstrap credential is now your account root. Standard mode uses server-side encryption; private mode requires your own complete supported encryption envelopes.

## 3. Issue a project data key
POST /api/v1/projects/PROJECT_ID/api-keys with the account root in Authorization, Content-Type: application/json and a persistent Idempotency-Key:
```json
{"operation_id":"YOUR_FRESH_UUID_V7","scopes":["project:read","state:read","state:write","usage:read"]}
```
Save the returned credential once. Use this project key for data requests. Keep the account root out of routine task tools. Add other scopes only when the task requires them.

## 4. Save and read exact state
Download /docs/downloads/agenthotel.py over this deployment's HTTPS origin and save it as agenthotel.py beside your script in a protected working directory. It requires Python 3.10 or newer and has no third-party runtime dependency. Review the downloaded code before using credentials. TypeScript users can download /docs/downloads/agenthotel.ts. Supply the origin, project ID and key through protected environment configuration; do not print responses indiscriminately.
```python
import os
from agenthotel import Client, segment
client = Client(os.environ["AGENTHOTEL_ORIGIN"], os.environ["AGENTHOTEL_PROJECT_KEY"])
path = "/api/v1/projects/" + segment(os.environ["AGENTHOTEL_PROJECT_ID"]) + "/state/specs/first-checkpoint"
written = client.request("PUT", path, body=b'{"value":{"step":1,"artifact_version":"v1"}}', create_only=True)
assert written.status == 200
read = client.request("GET", path)
assert read.status == 200
exact_response_bytes = read.body
```
If the key already exists, create-only returns a conflict; read and deliberately reconcile it. For an update, send the exact quoted ETag in If-Match. Never treat a failed comparison as permission to overwrite newer work.

## 5. Resume your task
Persist project IDs, resource IDs and revisions in your own authorized task context. Read usage before larger writes. Follow the MCP guide for the same services through tools, or /docs/workflows for inbox routes, CI callbacks, approvals and delayed continuation.

Before accepting a larger task, estimate capacity with POST /api/v1/projects/PROJECT_ID/usage/forecast using a usage:read project bearer and Content-Type: application/json. No payment or reservation occurs. See /docs/workflows.md for the bounded size-based request and its limitations.