# RedSwitches API

The RedSwitches API lets your own tools read your account, order instant servers from your account credit, and manage and power the servers you have. It is a plain JSON API over HTTPS.

> **Note.** The API is in private beta and open by invitation only. If the API tab is missing under Settings in your client area, your account has not been invited yet. Ask your account manager or support.

## What you can do

- Read your account, servers, traffic, orders, invoices, saved SSH keys and the instant servers on offer.
- Order an instant server, paid from your account credit, with a dry run that shows the exact total first.
- Rename servers, request reverse DNS, and add or remove saved SSH keys.
- Power servers on, off and reboot them, and follow each action until it is done.

> **Beta.** Cancellation requests, reinstall and rescue are built and in beta: RedSwitches switches them on (reinstall and rescue are off unless turned on). Each is marked on its page.

## The basics

| | |
|---|---|
| Base URL | `https://api.redswitches.com/v1`. `GET https://api.redswitches.com/` returns a small JSON index. |
| Docs | `https://api.redswitches.com/docs/` |
| Format | JSON in, JSON out. Times are UTC in ISO 8601 (`2026-11-15T09:30:00Z`). |
| Authentication | `Authorization: Bearer <key>`. See [Authentication and keys](authentication.md). |
| Ids | Typed strings: `srv_123` (server), `ord_456` (order), `inv_789` (invoice), `ofr_12` (offer), `sshkey_7` (SSH key), `act_42` (action). |
| Money | Decimal strings such as `"129.00"`, except order totals, which are minor units such as `"12900"`. |
| Writes | Every POST and DELETE needs an `Idempotency-Key` header. See [Idempotency and retries](idempotency.md). |

A first request:

```bash
curl -sS https://api.redswitches.com/v1/auth/verify \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"
```

```json
{
  "id": "key_5",
  "label": "monitoring",
  "hint": "a1B2",
  "env": "live",
  "permissions": ["read"],
  "effective_permissions": ["read"],
  "expires_at": "2027-02-13T09:30:00Z"
}
```

## Where to go next

- [Quickstart](quickstart.md): turn on API access, create a key, make your first call.
- [Authentication and keys](authentication.md): permissions, server lists, expiry and revocation.
- [Idempotency and retries](idempotency.md): how to repeat a write safely.
- [Rate limits and errors](errors.md): every error code and what to do about it.
- [Ordering guide](guide-ordering.md) and [Power and actions guide](guide-power.md).
- Resources: [Account](account.md), [Offers](offers.md), [Servers](servers.md), [Reverse DNS](rdns.md), [Orders](orders.md), [Invoices](invoices.md), [SSH keys](ssh-keys.md), [Actions and power](actions.md), [Cancellation](cancellation.md), [Reinstall](reinstall.md), [Rescue](rescue.md).
- [API reference](reference.md): every endpoint and field, built from the OpenAPI file.
- Tools: [Terraform](terraform.md), [CLI](cli.md), [MCP for agents](mcp.md).
- [Changelog](changelog.md).

## SDKs and tools

The examples show curl and the official SDKs:

| Language | Package | Entry point |
|---|---|---|
| TypeScript | `@redswitches/api` | `new RedSwitches({ apiKey })` |
| Python | `redswitches` | `Client(api_key=...)` |
| Go | `github.com/redswitches/redswitches-go` | `redswitches.NewClient(key)` |

> **Note.** The SDKs, the `rxctl` CLI, the Terraform provider and the MCP server are built but not published yet. See [SDKs](sdks.md). Until they are, use curl or any HTTP client: the API itself is all you need.

## For agents

A plain-text index is at `llms.txt`, and every page has a Markdown twin under `md/` (this page is `md/index.md`).