# Build on Pantheon

> Take an agent from account setup to a running application.

## Get in

Sign up in the dashboard. Create a key and copy its secret immediately.

| Method | Route             |
| ------ | ----------------- |
| `POST` | `/v1/auth/signup` |
| `POST` | `/v1/auth/keys`   |

**Pantheon guarantees:** Pantheon shows the key secret once and stores its hash.

Read [Get an API key](https://pantheon-todo.alethiconsulting.com/docs/get-a-key).

## Model the work

Register tool definitions with input and output schemas. Create a version for each contract change.

| Method | Route                          |
| ------ | ------------------------------ |
| `POST` | `/v1/tools`                    |
| `POST` | `/v1/tools/{tool_id}/versions` |

Register tools and manage versions from the dashboard [Tools](https://pantheon-todo.alethiconsulting.com/dashboard/tools) page.

**Pantheon guarantees:** Pantheon keeps versioned tool contracts for deployment snapshots. Your application executes application tools.

Read [Application tools](https://pantheon-todo.alethiconsulting.com/docs/application-tools).

## Define the agent

Choose a slug and a model from the models list. Set the system prompt, tool ids, skills, and sandbox policy.

| Method | Route        |
| ------ | ------------ |
| `GET`  | `/v1/models` |
| `POST` | `/v1/agents` |

Create and edit agents, publish deployments, and review deployment history on the dashboard [Agents](https://pantheon-todo.alethiconsulting.com/dashboard/agents) page.

**Pantheon guarantees:** Pantheon stores the agent definition. Publish it before creating sessions by slug.

Read [Quickstart](https://pantheon-todo.alethiconsulting.com/docs/quickstart).

## Publish

Create a deployment for your agent. Activate it to select it for new slug sessions.

| Method | Route                           |
| ------ | ------------------------------- |
| `POST` | `/v1/deployments`               |
| `POST` | `/v1/deployments/{id}/activate` |

See [Roll back a deployment](https://pantheon-todo.alethiconsulting.com/docs/sessions-and-runs#rollback) for activation behavior.

**Pantheon guarantees:** New slug sessions use the active deployment, or the newest publication when none is active. Existing sessions stay pinned.

Read [Core concepts](https://pantheon-todo.alethiconsulting.com/docs/concepts).

## Wire it in

Use the chat components or create a session by agent slug through the API. Start a run with your message and stream events.

| Method | Route                                            |
| ------ | ------------------------------------------------ |
| `POST` | `/v1/sessions`                                   |
| `POST` | `/v1/sessions/{session_id}/runs`                 |
| `GET`  | `/v1/sessions/{session_id}/events/stream`        |
| `POST` | `/v1/sessions/{session_id}/runs/{run_id}/resume` |
| `POST` | `/v1/sessions/{session_id}/runs/{run_id}/cancel` |

Enable `event_deltas` for live output. See [Event stream](https://pantheon-todo.alethiconsulting.com/docs/events).

Handle each tool pause in your application. Resume with the matching `tool_call_id` and result.

See [Application tools](https://pantheon-todo.alethiconsulting.com/docs/application-tools) for the pause and resume contract.

On `SESSION_BUSY`, inspect the active run. Wait, resume pending tools, or cancel before sending another message.

Use [Chat components](https://pantheon-todo.alethiconsulting.com/docs/chat-components) for a ready-made chat UI.

**Pantheon guarantees:** Pantheon allows one active run per session. Runs pause for application tools and resume with their results.

Read [Sessions and runs](https://pantheon-todo.alethiconsulting.com/docs/sessions-and-runs).

## Run it

Read error codes and request ids. Revoke exposed keys from the dashboard. Review audit records.

| Method   | Route                    |
| -------- | ------------------------ |
| `DELETE` | `/v1/auth/keys/{key_id}` |
| `GET`    | `/v1/audit/records`      |

Use a signed-in dashboard session to revoke keys. API keys cannot manage other keys.

See [Manage keys](https://pantheon-todo.alethiconsulting.com/docs/get-a-key#manage) and [Audit routes](https://pantheon-todo.alethiconsulting.com/docs/api-reference).

Filter sessions, inspect usage and events, and archive sessions from the dashboard [Sessions](https://pantheon-todo.alethiconsulting.com/dashboard/sessions) page.

**Pantheon guarantees:** Errors include codes and request ids. Revoked keys stop working. Audit records track tenant actions.

Read [Error handling](https://pantheon-todo.alethiconsulting.com/docs/errors).

## Iterate

Edit your agent. Create a new tool version when its contract changes. Publish and activate a new deployment. To roll back, activate an earlier published deployment.

| Method | Route                           |
| ------ | ------------------------------- |
| `PUT`  | `/v1/agents/{agent_id}`         |
| `POST` | `/v1/tools/{tool_id}/versions`  |
| `POST` | `/v1/deployments`               |
| `POST` | `/v1/deployments/{id}/activate` |

See [Roll back a deployment](https://pantheon-todo.alethiconsulting.com/docs/sessions-and-runs#rollback) for activation behavior.

**Pantheon guarantees:** New slug sessions receive the active deployment. Existing sessions keep their pinned deployment.

Read [Endpoints and schemas](https://pantheon-todo.alethiconsulting.com/docs/api-reference).