# RedSwitches API

> REST API for RedSwitches dedicated servers (private beta, invite-only). Read your account, servers, traffic, orders,
> invoices, saved SSH keys and the instant servers on offer; order an instant server paid from account credit; rename
> servers, request reverse DNS, manage saved SSH keys, and power servers on, off or reboot them.
> Base URL: https://api.redswitches.com/v1 (docs: https://api.redswitches.com/docs/) — JSON over HTTPS — `Authorization: Bearer <key>` (keys start
> with `rsw_live_`; never put a key in a URL: it is revoked) — every POST/DELETE needs an `Idempotency-Key` header.

Important rules for agents:

- Ids are typed strings: srv_ (server), ord_ (order), inv_ (invoice), ofr_ (offer), sshkey_ (SSH key), act_ (action).
- Money is a decimal string ("129.00"), except ordering, which uses minor units ({"amount":"15609","currency":"EUR"}).
- To order: GET /offers, then POST /orders?dry_run=true, then POST /orders with expected_total = the dry run's total and
  a new Idempotency-Key, then poll GET /orders/{id} every poll_after seconds until each service's delivery is "ready".
  Orders spend real money from account credit: confirm the total with the user first.
- Power is asynchronous: POST /servers/{id}/power answers 202 with an action; poll GET /actions/{id}.
- After a timeout, retry with the SAME Idempotency-Key and body. Retry only on network errors, 429, 503 and in_progress.
- Errors are {"error":{"code","message","request_id","details"?}}; act on `code`, never on `message`.
- Items marked "Beta — rolling out" may not answer yet.

## Docs

- [Overview](md/index.md): what the API does, base URL, ids, money format
- [Quickstart](md/quickstart.md): turn on API access, create a key, first request
- [Authentication and keys](md/authentication.md): Bearer keys, permissions, server lists, expiry, revocation
- [Idempotency and retries](md/idempotency.md): what a repeated write returns
- [Rate limits and errors](md/errors.md): limits, headers, every error code and details key
- [Ordering guide](md/guide-ordering.md): dry run, expected_total, polling until ready
- [Power and actions guide](md/guide-power.md): power verbs, action states, limits, the power-off brake

## Resources

- [Account and key](md/account.md): GET /auth/verify, GET /account
- [Offers](md/offers.md): GET /offers, GET /offers/{id}
- [Servers](md/servers.md): GET /servers, GET /servers/{id}, GET /servers/{id}/traffic, POST /servers/{id}/label
- [Reverse DNS](md/rdns.md): GET and POST /servers/{id}/rdns
- [Orders](md/orders.md): GET /orders, GET /orders/{id}, POST /orders
- [Invoices](md/invoices.md): GET /invoices, GET /invoices/{id} (read_billing)
- [SSH keys](md/ssh-keys.md): GET and POST /ssh-keys, DELETE /ssh-keys/{id}
- [Actions and power](md/actions.md): POST /servers/{id}/power, GET /actions/{id}
- [Cancellation (beta)](md/cancellation.md): GET, POST and DELETE /servers/{id}/cancel-request
- [Reinstall (beta)](md/reinstall.md): GET /servers/{id}/os, POST /servers/{id}/reinstall
- [Rescue and one-time credentials (beta)](md/rescue.md): POST /servers/{id}/rescue, GET /actions/{id}/credentials (readable once; store it at once)

## Reference

- [API reference](md/reference.md): every endpoint, object and error code
- [OpenAPI 3.1 (JSON)](openapi.json)
- [OpenAPI 3.1 (YAML)](openapi.yaml)

## Optional

- [SDKs](md/sdks.md): TypeScript @redswitches/api, Python redswitches, Go redswitches-go: install, retries, errors (not published yet)
- [Terraform provider](md/terraform.md): redswitches/redswitches (not published yet)
- [CLI: rxctl](md/cli.md) (not published yet)
- [MCP server](md/mcp.md): @redswitches/mcp, read-only unless --allow-writes (not published yet)
- [AI agents and assistants](md/agents.md): hosted MCP server https://mcp.redswitches.com/mcp (key as Authorization: Bearer, read-only unless X-RedSwitches-Allow-Writes: true), Claude Code plugin, GPT Action, function tools (not live yet)
- [llms-full.txt](llms-full.txt): every page in one file, with the rules for agents
- [Changelog](md/changelog.md)