---
order: 1
summary: 'Control-plane REST API: connectors, services, policy and the decision log.'
title: API
path: reference/api
status: published
---

# API

The control plane is a REST API. Everything the console and CLI do is
available here.

```
Base URL   https://api.proxility.scailabs.ai/v1
Auth       Authorization: Bearer <token>
Content    application/json
```

Tokens come from ScaiKey. A service token for automation is scoped to a realm
and a role — give CI a `realm:policy` token, not a tenant admin.

## Connectors

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/realms/{realm}/connectors` | List connectors and their state |
| `POST` | `/realms/{realm}/connectors` | Create a connector and return an enrolment token |
| `GET` | `/realms/{realm}/connectors/{name}` | One connector, with edge sessions and certificate expiry |
| `POST` | `/realms/{realm}/connectors/{name}/revoke` | Revoke the identity |

```bash
curl -X POST "$BASE/realms/prod/connectors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"dc1-a","description":"Amsterdam DC, rack 4"}'
```

The response carries `enrolment_token` **once**. It is not retrievable
afterwards; create another connector record if you lose it.

## Services

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/realms/{realm}/services` | List published services |
| `POST` | `/realms/{realm}/services` | Publish a service |
| `GET` | `/realms/{realm}/services/{name}` | One service |
| `DELETE` | `/realms/{realm}/services/{name}` | Unpublish |

```json
{
  "name": "payments",
  "connectors": ["dc1-a", "dc1-b"],
  "target": "10.20.4.17:8443",
  "protocol": "tcp"
}
```

## Policy

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/realms/{realm}/policy` | Current rule set, with a version |
| `PUT` | `/realms/{realm}/policy` | Replace the rule set |
| `POST` | `/realms/{realm}/policy/rules` | Add one rule |
| `DELETE` | `/realms/{realm}/policy/rules/{id}` | Remove one rule |
| `GET` | `/realms/{realm}/policy/history` | Change history with diffs |

`PUT` takes the version you read as `If-Match`. A mismatch returns `409`
rather than overwriting someone else's concurrent change — important when both
a human and a CI pipeline manage policy.

## Decision log

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/realms/{realm}/decisions` | Query decisions |

Filters: `from`, `to`, `verdict` (`allow`/`deny`), `reason`, `since`, `until`,
`limit`. Results are newest first and paginate with an opaque `cursor`.

```bash
curl -G "$BASE/realms/prod/decisions" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "verdict=deny" \
  --data-urlencode "since=2026-11-01T00:00:00Z"
```

## Errors

```json
{"error": {"code": "POLICY_VERSION_CONFLICT", "message": "..."}}
```

| Status | Meaning |
|---|---|
| `400` | Malformed request |
| `401` | Missing or invalid token |
| `403` | Token lacks the role for this realm |
| `404` | Unknown realm, connector or service |
| `409` | Version conflict, or name already in use |
| `429` | Rate limited. Honour `Retry-After` |
