---
summary: 'The ScaiLine /v1 control-plane and render API: authentication, conventions
  and endpoints.'
audience: integrators
order: 1
title: API
path: reference/api
status: published
---

# API

The console uses the same API that is available to integrations. The API describes itself in an
OpenAPI document, which is not yet exposed on the public host; ask ScaiLabs for a copy. Paths may
still change before general availability.

## Conventions

* **Base URL:** `https://scailine.scailabs.ai/v1`.
* **Authentication:** `Authorization: Bearer <token>`, where the token is one of:
  * a console session (ScaiKey sign-in through `/auth/login` and `/auth/callback`);
  * an **API key** (`slk_…`), created under **API keys** in the console. A key carries a
    subset of its creator's permissions and can expire; the plaintext is shown once;
  * a milter node token (`smn_…`), valid only for the milter endpoints.
* **Permissions:** every endpoint requires a permission (`templates.write`, `rules.read`, …)
  from the caller's roles (`tenant_admin`, `designer`, `campaign_manager`, `legal`,
  `auditor`, `user`). Roles come from ScaiKey groups or are assigned to individual people under
  **Settings**.
* **Tenant scoping:** tenant paths take the organisation's id (`tnt_…`). Another organisation's
  resources answer `404`, never `403`.
* **Errors:** `{"detail": "…", "code": "…"}` with the HTTP status. Validation errors are `422`
  and may add `errors: [{"path": "…", "message": "…"}]`.
* **Pagination:** `?page=&page_size=` (default 25, maximum 100); responses are
  `{items, total, page, page_size}`.
* **Ids** are prefixed strings, such as `tnt_`, `prf_`, `tpl_`.
* **Request ids:** `X-Request-ID` is returned on every response; quote it to support.

## Endpoints

Tenant paths below start with `/tenants/{t}`.

| Area | Method and path | Purpose |
|---|---|---|
| Session | `POST /auth/login`, `POST /auth/callback`, `POST /auth/refresh`, `POST /auth/logout` | ScaiKey sign-in and session lifecycle. |
| Session | `GET /auth/me` | The signed-in user, organisation and permissions. |
| Organisations | `GET /tenants`, `GET` / `PATCH /tenants/{t}` | Organisations you can see; settings. Organisations are created in ScaiKey. |
| Domains | `GET` / `POST /tenants/{t}/domains`, `GET` / `PATCH` / `DELETE …/{id}`, `POST …/{id}/verify` | Sending domains, the *internal* flag, TXT verification. |
| Mail flow | `GET` / `POST /tenants/{t}/platforms`, `GET` / `PATCH` / `DELETE …/{id}` | Mail-flow connections (`m365`, `milter`, `smtp`, `scaisend`, `messages`), shadow mode, activation. |
| Mail flow | `GET /tenants/{t}/platforms/{id}/m365-script` | The Exchange Online PowerShell for a Microsoft 365 connection. |
| Mail flow | `GET` / `POST /tenants/{t}/milter-nodes`, `DELETE …/{id}` | Enrol and revoke milter nodes. |
| Directory | `GET` / `POST /tenants/{t}/directory-sources`, `GET` / `PATCH` / `DELETE …/{id}` | Directory sources. |
| Directory | `GET /tenants/{t}/groups`, `POST /tenants/{t}/labels` | Group lookup; names for ids. |
| Attributes | `GET` / `POST /tenants/{t}/attributes/mappings`, `GET` / `PATCH` / `DELETE …/{id}`, `GET …/attributes/effective` | Source order per attribute; the effective result including defaults. |
| Attributes | `GET` / `POST /tenants/{t}/attributes/definitions`, `GET` / `PATCH` / `DELETE …/{id}` | Custom attribute definitions. |
| Attributes | `POST /tenants/{t}/attributes/install-pack`, `GET …/attributes/pack-status` | Install the attribute pack in ScaiKey (tenant administrators); its status. |
| Profiles | `GET /tenants/{t}/profiles`, `GET …/profiles/search`, `GET …/profiles/{p}` | People, with attribute values and their sources. |
| Assets | `GET` / `POST /tenants/{t}/assets`, `DELETE …/{id}` | Uploaded images. |
| Brand kits | `GET` / `POST /tenants/{t}/brand-kits`, `GET` / `PATCH` / `DELETE …/{id}` | Logos, colours, fonts, disclaimer. |
| Templates | `GET` / `POST /tenants/{t}/templates`, `GET` / `PATCH` / `DELETE …/{id}`, `GET …/templates/catalogue` | Templates (delete archives) and the element catalogue. |
| Templates | `PUT …/templates/{id}/draft`, `POST …/templates/{id}/publish`, `POST …/templates/preview` | Save a draft, publish, render a preview. |
| Templates | `GET` / `POST …/templates/{id}/versions`, `GET …/versions/{v}`, `POST …/versions/{v}/publish`, `POST …/versions/{v}/restore` | Version history. |
| Rules | `GET` / `POST /tenants/{t}/rules`, `GET` / `PATCH` / `DELETE …/{id}`, `POST …/rules/test` | Rules and the rule tester. |
| Campaigns | `GET` / `POST /tenants/{t}/campaigns`, `GET` / `PATCH` / `DELETE …/{id}` | Banners with a time window. |
| Legal | `GET` / `POST /tenants/{t}/legal-entities`, `GET` / `PATCH` / `DELETE …/{id}` | Legal entities and their registration data. |
| Signatures | `GET /signatures/me?compose=new\|reply&scope=internal\|external` | The calling user's compiled signature. |
| Signatures | `GET /signatures/me/domains` | The organisation's domains, for internal/external decisions in clients. |
| Signatures | `GET /tenants/{t}/profiles/{p}/signature?compose=&scope=` | Any person's compiled signature. |
| Signatures | `GET /tenants/{t}/bundles`, `GET …/profiles/{p}/bundle` | Metadata of compiled signatures. |
| Statistics | `GET /tenants/{t}/stats?days=` | Processing counts per day and outcome. |
| Access | `GET` / `POST /tenants/{t}/admin/group-roles`, `DELETE …/{id}` | ScaiKey group → role. |
| Access | `GET` / `POST /tenants/{t}/admin/role-bindings`, `DELETE …/{id}` | Roles for individual people. |
| Access | `GET` / `POST /tenants/{t}/api-keys`, `DELETE …/{id}` | API keys. |
| Self | `GET /profiles/me` | The caller's own profile. |
| Milter | `GET /milter/snapshot?since=`, `POST /milter/stats` | Used by milter nodes with their node token. |
| Webhooks | `POST /webhooks/scaikey`, `POST /webhooks/scaicontrol` | Signed inbound events. |
| Health | `GET /health`, `GET /ready` | Liveness and readiness; not exposed publicly. |

## Example: the calling user's signature

```bash
curl -s "https://scailine.scailabs.ai/v1/signatures/me?compose=reply&scope=external" \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "html": "<table …>…</table>",
  "text": "Jan Jansen\nSales Engineer, ScaiLabs\n+31 45 …",
  "bundle_version": 12,
  "components_applied": ["legal"]
}
```

`components_applied` lists which separately managed parts (`legal`, `banner`) the signature
contains; a client that inserts this signature sets `X-ScaiLine-Client` so the server does not add
them a second time.

`404` with `code: bundle_missing` means nothing has been compiled for this person yet (no rule or
template applies); `503` means the signature store is briefly unavailable, so retry.