---
title: Service registry
path: reference/api/registry
status: published
---

# Service registry

**4 endpoints** in this group. All paths are prefixed with `/api/v1`.

## Endpoints in this group

- [`POST /api/v1/registry/heartbeat`](#post-api-v1-registry-heartbeat) — Heartbeat
- [`DELETE /api/v1/registry/register`](#delete-api-v1-registry-register) — Deregister Service
- [`POST /api/v1/registry/register`](#post-api-v1-registry-register) — Register Service
- [`PUT /api/v1/registry/register`](#put-api-v1-registry-register) — Reregister Service

---

### POST `/api/v1/registry/heartbeat` — Heartbeat {#post-api-v1-registry-heartbeat}

Process a service heartbeat.

Updates the service's last heartbeat timestamp, resets failure count,
and restores degraded services to active status.

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `HeartbeatRequest` — {`slug`, `status`, `version`, `uptime_seconds` + 5 more}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_HeartbeatResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### DELETE `/api/v1/registry/register` — Deregister Service {#delete-api-v1-registry-register}

Deregister a service from ScaiControl.

Checks that no active subscriptions exist before deregistering.

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `DeregistrationRequest` — {`slug`, `reason`}


**Responses**:

- `204` — Successful Response. Returns: —
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/registry/register` — Register Service {#post-api-v1-registry-register}

Register a new service with ScaiControl.

The calling service must authenticate as a service account.
Auto-approval is granted to known ScaiLabs internal services.

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `RegistrationRequest` — {`slug`, `name`, `version`, `description` + 9 more}


**Responses**:

- `201` — Successful Response. Returns: `ApiResponse_RegistrationResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### PUT `/api/v1/registry/register` — Reregister Service {#put-api-v1-registry-register}

Re-register (update) an existing service.

Idempotent: updates service metadata, endpoints, and capabilities.
Tracks version changes.

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `RegistrationRequest` — {`slug`, `name`, `version`, `description` + 9 more}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_RegistrationResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}