---
title: "Hamster OSS API and developer docs"
description: "The Hamster OSS API: the MCP server on your team's instance (OAuth, system:access) and the account MCP server and REST API at tryhamster.dev, with endpoints and example requests."
canonical: "https://tryhamster.dev/developers"
last-updated: "2026-11-05"
---

# Hamster OSS API

> The Hamster OSS API: the MCP server on your team's instance (OAuth, system:access) and the account MCP server and REST API at tryhamster.dev, with endpoints and example requests.

*The Hamster OSS API is the MCP server on your team's instance. Agents and scripts call it at `https://<your-team>.tryhamster.dev/mcp` with an OAuth access token.*

The [OpenAPI 3.1 document](https://tryhamster.dev/openapi.json) describes the same endpoints for tools that read OpenAPI.

## Access

Sign up free at [tryhamster.dev/signup](https://tryhamster.dev/signup), save and verify a card for $15 in starter credit, and create an instance; [Get access](https://tryhamster.dev/get-access) has every step and [Pricing](https://tryhamster.dev/pricing) has the prices. If someone at Hamster invited you, claim the invitation instead.

There's no sandbox or test environment, and no account-wide API key. To try the API, use the $15 starter credit on a Micro instance. Access is self-serve: an agent registers its own OAuth client at `https://tryhamster.dev/oauth/register` (RFC 7591 dynamic client registration), with no secret and no request to Hamster, and the person approves it in the browser. There are two kinds of token. Account tokens come from tryhamster.dev's own OAuth server: they let an agent act for one person on the account MCP server and the `/api/v1/agent` API, within the scopes the person approved. Instance tokens come from each instance: each one works for one instance and one project.

## Quickstart

1. Add `https://<your-team>.tryhamster.dev/mcp` to your MCP client as a remote (HTTP) server. Clients that support MCP authorization find the authorization server on their own; [Hamster OSS MCP server](https://tryhamster.dev/docs/mcp) covers client setup.
2. When the client opens your instance in the browser, sign in and choose the project your agent works on.
3. Call the `read` tool with path `/`. It returns every path the tools accept.

To run Hamster OSS on your own machine, install the CLI:

```sh
curl -fsSL https://dl.tryhamster.dev/install.sh | sh
```

## Authentication

Each instance is the OAuth authorization server for its own MCP server.

- `GET /.well-known/oauth-protected-resource/mcp` — protected resource metadata (RFC 9728): the resource, its authorization server and the `system:access` scope.
- `GET /.well-known/oauth-authorization-server` — authorization server metadata (RFC 8414) with the authorize, token and registration endpoints.
- `POST /oauth/register` — dynamic client registration (RFC 7591). Every client registers as a public client with no secret. The metadata lists `registration_endpoint` only when the instance accepts registration.
- `/oauth/authorize` and `/oauth/token` — the authorization code flow with S256 PKCE. The only scope is `system:access`. Access tokens expire and there are no refresh tokens, so a client reconnects to get a new one.
- **Connect your agent** in Studio, or **Agents** in your settings — an expiring token for one project, without OAuth.

Send the token as `Authorization: Bearer <token>`. A request without a valid token gets `401` and a `WWW-Authenticate` header that points to the protected resource metadata. `/mcp` never accepts browser cookies.

Signing in to the dashboard at tryhamster.dev uses a separate identity provider, `https://auth.tryhamster.dev` (OpenID Connect). It doesn't issue tokens for MCP servers, and the dashboard's own API under `/api/v1`, outside `/api/v1/agent`, never accepts agent tokens.

## Account API at tryhamster.dev

An agent can sign a person up and create an instance for them. The person approves the agent in the browser: they sign up or sign in, verify their email, accept the terms and approve the agent. There are two equal surfaces: the Hamster OSS account MCP server, `POST https://tryhamster.dev/mcp`, and its REST twin, `https://tryhamster.dev/api/v1/agent/*`. The [OpenAPI document](https://tryhamster.dev/openapi.json) has every REST operation.

- tryhamster.dev is the authorization server for both. A call without a token gets `401` and a `WWW-Authenticate` header that points to `/.well-known/oauth-protected-resource/mcp` (MCP) or `/.well-known/oauth-protected-resource` (REST) and names all four scopes, so one approval covers the whole setup. A token is bound to the resources it was issued for: both, unless the client asked for one.
- Self-serve client registration: `POST https://tryhamster.dev/oauth/register` with your client metadata (RFC 7591) answers `201` with a `client_id`. Every client is public (`token_endpoint_auth_method` `none`), and a Client ID Metadata Document URL also works as `client_id`. The authorization server metadata at `https://tryhamster.dev/.well-known/oauth-authorization-server` lists it as `registration_endpoint`.
- Scopes: `account:read` (account and instance status), `account:write` (redeem a Design Partner Code), `instances:write` (create instances, and the person's first organization) and `billing:write` (links to Stripe-hosted pages that save a card without payment or add funds).
- Ordinary onboarding uses hosted Checkout; agents never handle card details. An eligible first card earns $15 after verification on a Stripe-hosted setup page, without a payment. Later funding also happens on a Stripe-hosted page the person completes.
- `status` reports `accountCreated` separately from instance readiness and includes each organization’s `starterCredit` status for billing roles. `create_instance` defaults to Micro and keeps the same request identity through activation. After credit settles, the original pending creation resumes. `get_instance` returns `mcpUrl` only after readiness checks pass.
- `add_payment_method` accepts optional `requestId` and `organizationId` and opens card setup. The REST equivalent is `POST /api/v1/agent/billing/checkout` with `mode: "setup"`; omit `amountCents`. Use `mode: "payment"` and `amountCents` for a top-up; omitting `mode` preserves payment behavior.
- Give the person the returned checkout `url` unchanged. It is a `https://tryhamster.dev/checkout/…` bearer link that redirects to Stripe while the session is open, or to the completion or expiry page afterward. It requires no sign-in and is never cached.
- On MCP, `add_funds` takes an optional `requestId`, like `create_instance`. Without one, a retry returns the same Stripe page; once the person has paid it, the tool answers `{"paid": true, "detail": …}` instead, and the agent passes a new `requestId` to add funds again. With an explicit `requestId`, a paid page stays the answer, as on REST.
- Without a token, the MCP server answers `initialize`, `tools/list` and the tools `get_pricing`, `search_docs`, `fetch_doc` and `get_install_command`. The tools `status`, `create_instance`, `get_instance`, `add_payment_method`, `add_funds` and `redeem_code` need a token with the matching scope; without one, they get the `401` challenge before their arguments are read.
- When an instance is ready, `get_instance` returns its MCP URL and the commands to connect Claude Code, Cursor and Codex.
- Errors are RFC 9457 problem details (`application/problem+json`) with a stable `code`; a `402` carries `next_action`. On MCP, a tool error is a result with `isError` and the problem as JSON in its text content, with no `structuredContent`. Both surfaces share a limit of 120 requests per client per minute, advertised in `RateLimit-Policy` and `RateLimit` headers; over it, the answer is `429` with `Retry-After`. Creating requests accept an `Idempotency-Key` header in place of `requestId`; reusing a key with a different body gets `422` (`idempotency_key_reused`), and reusing a `requestId` with other parameters gets `409` (`conflict`).

## Endpoints

- `POST https://<your-team>.tryhamster.dev/mcp` — MCP over Streamable HTTP. Send a JSON-RPC 2.0 message and the answer is JSON. Needs a bearer token.
- `GET https://<your-team>.tryhamster.dev/.well-known/oauth-protected-resource/mcp` — protected resource metadata. Public.
- `GET https://<your-team>.tryhamster.dev/.well-known/oauth-authorization-server` — authorization server metadata. Public.
- `GET https://dl.tryhamster.dev/channels/tracks.json` — the release track catalog the installer reads. Public. Its signature is at `tracks.json.sig`.
- `POST https://tryhamster.dev/mcp` — the Hamster OSS account MCP server (protocol 2025-11-25; 2025-06-18 and 2025-03-26 also accepted). Docs and pricing tools need no token; account tools need OAuth with tryhamster.dev.
- `GET https://tryhamster.dev/api/v1/agent/catalog` — sizes, prices and usage rates. Public. The other `/api/v1/agent/*` endpoints need a token.
- `POST https://tryhamster.dev/oauth/register` — dynamic client registration for the account MCP server and `/api/v1/agent`. Public.

[API versioning and deprecation](https://tryhamster.dev/docs/api-versioning) explains how each surface is versioned and how a breaking change is announced.

## Example requests

Read the protected resource metadata:

```sh
curl -sS https://<your-team>.tryhamster.dev/.well-known/oauth-protected-resource/mcp
```

```json
{"authorization_servers":["https://<your-team>.tryhamster.dev"],"resource":"https://<your-team>.tryhamster.dev/mcp","scopes_supported":["system:access"]}
```

List the MCP tools with an access token:

```sh
curl -sS https://<your-team>.tryhamster.dev/mcp \
  -H "Authorization: Bearer $HAMSTER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

The result lists six tools: `create`, `read`, `update`, `delete`, `search` and `message`.

Search these docs through the Hamster OSS account MCP server, which needs no token for this tool:

```sh
curl -sS https://tryhamster.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"oauth scope"}}}'
```

Register an OAuth client for the account API, with no key to request:

```sh
curl -sS https://tryhamster.dev/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"My agent","redirect_uris":["http://127.0.0.1:8765/callback"],"grant_types":["authorization_code","refresh_token"],"response_types":["code"],"token_endpoint_auth_method":"none"}'
```

The answer is `201 Created`:

```json
{"client_id":"dcr_…","client_id_issued_at":1793919612,"client_name":"My agent","grant_types":["authorization_code","refresh_token"],"redirect_uris":["http://127.0.0.1:8765/callback"],"response_types":["code"],"token_endpoint_auth_method":"none"}
```

Read the public release catalog:

```sh
curl -sS https://dl.tryhamster.dev/channels/tracks.json
```

## Machine payments

The REST-only `POST /api/v1/agent/billing/topups` operation accepts MPP Stripe Shared Payment Tokens when enabled on the merchant account. Request `billing:pay` explicitly through OAuth consent; default scopes, existing grants and auth.md claim grants do not include it. The person must be an owner or admin of the organization. ChatGPT clients cannot use this operation.

Send `requestId` and `organizationId` as UUIDs and `amountCents` between 1000 and 1000000. Keep the OAuth bearer token in `Authorization`. The initial `402` response carries a signed `WWW-Authenticate: Payment` challenge; retry with the MPP credential in `Payment-Authorization`. The successful response includes `Payment-Receipt` and `paid: true`. Retry uncertain results with the same request ID and body. Payments add prepaid funds without saving a card, granting starter credit, or enabling automatic top-up. The [OpenAPI document](https://tryhamster.dev/openapi.json) declares its `x-payment-info` offer; the runtime challenge supplies the exact amount.