Administration.

These calls need an administrator and a key with the admin scope. Several of them also need another license feature, named on the call. Reading the license does not.

See the API reference for the key, errors, and the licence spelling of the license routes.

License

GET /api/v1/license

What this installation is licensed to do: plan, speed, features, users and jobs. Answers in Free mode too.

Who. Any user with an API key. The key does not need a particular scope. This is the one API-key call that still answers when the license does not include the REST API, so a script can see why the others return 402. The same call is also at GET /api/v1/licence.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/admin/license

Load a license. Checked before it replaces the old one.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. None.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "not a valid license, or not for this install"
  }
}

DELETE /api/v1/admin/license

Remove the license. The server drops to Free mode at once; the file is set aside.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

GET /api/v1/admin/license/free-mode

Who stays active and which jobs keep running in Free mode.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

PUT /api/v1/admin/license/free-mode

Pick the active users and the running jobs.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. The raw bytes of the piece. Not JSON.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "more than the limit was picked"
  }
}

POST /api/v1/admin/license/request/preview

The license request email, with its request code, before it is sent.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. None.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/admin/license/request/send

Send the license request to [email protected] through this server's email settings, or return it to send by hand.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. None.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/admin/license/trial/start

Ask license.farwing.io for a 30-day trial. The only call this server makes to farwing.io.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. None.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/admin/license/trial/verify

Enter the code from the trial email. The trial license is loaded at once.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. None.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Audit

GET /api/v1/admin/audit

The audit trail. Read-only, including for administrators.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

{
  "items": [
    {
      "id": 1,
      "at": "2026-10-05T18:00:00Z",
      "actorKind": "example",
      "action": "release"
    }
  ],
  "nextBefore": 1,
  "actions": [
    "release"
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "an unknown actorKind"
  }
}

GET /api/v1/admin/audit.csv

The same rows as a CSV file, with the same filters. No paging: the file is the whole window.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Settings

GET /api/v1/admin/transfer-settings

How long a transfer link stays valid before its transfer starts: {linkMinutes, defaultMinutes, minMinutes, maxMinutes, resumeHours}.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

{
  "linkMinutes": 1,
  "defaultMinutes": 1,
  "minMinutes": 1,
  "maxMinutes": 1,
  "resumeHours": 24
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

PUT /api/v1/admin/transfer-settings

Change it with {linkMinutes}. A value outside its range is refused, not clamped. Applies to links made from then on.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "linkMinutes": 1
}

Success. 200.

{
  "linkMinutes": 1,
  "defaultMinutes": 1,
  "minMinutes": 1,
  "maxMinutes": 1,
  "resumeHours": 24
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a value outside its allowed range"
  }
}

GET /api/v1/admin/sign-in-policy

Password rules, lockout and session timeout.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

{
  "passwordMinLength": 1,
  "passwordRequireMixedCase": true,
  "passwordRequireDigit": true,
  "passwordRequireSymbol": true,
  "requireTotp": true,
  "lockoutAttempts": 1,
  "lockoutMinutes": 1,
  "sessionIdleMinutes": 1
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

PUT /api/v1/admin/sign-in-policy

Change them. A value outside its range is refused, not clamped.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "passwordMinLength": 1,
  "passwordRequireMixedCase": true,
  "passwordRequireDigit": true,
  "passwordRequireSymbol": true,
  "requireTotp": true,
  "lockoutAttempts": 1,
  "lockoutMinutes": 1,
  "sessionIdleMinutes": 1
}

Success. 200.

{
  "passwordMinLength": 1,
  "passwordRequireMixedCase": true,
  "passwordRequireDigit": true,
  "passwordRequireSymbol": true,
  "requireTotp": true,
  "lockoutAttempts": 1,
  "lockoutMinutes": 1,
  "sessionIdleMinutes": 1
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a value outside its allowed range"
  }
}

GET /api/v1/admin/appearance

Company name, logos, accent color, sign-in page text, globe route, footer links and notice, and what the accent measures against white.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

{
  "appearance": {
    "companyName": "example",
    "accent": "example",
    "logo": "example",
    "logoDark": "example",
    "eyebrow": "example",
    "headline": "example",
    "subtext": "example",
    "linkLabel": "example",
    "linkUrl": "example",
    "cardTitle": "example",
    "cardSubtitle": "example",
    "globe": true,
    "routeFrom": "example",
    "routeTo": "example",
    "footerLinks": [
      {
        "label": "example",
        "url": "example"
      }
    ],
    "notice": "example"
  },
  "accentContrast": 1,
  "included": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

PUT /api/v1/admin/appearance

Change them.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include custom branding.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "companyName": "example",
  "accent": "example",
  "logo": "example"
}

Success. 200.

{
  "appearance": {
    "companyName": "example",
    "accent": "example",
    "logo": "example",
    "logoDark": "example",
    "eyebrow": "example",
    "headline": "example",
    "subtext": "example",
    "linkLabel": "example",
    "linkUrl": "example",
    "cardTitle": "example",
    "cardSubtitle": "example",
    "globe": true,
    "routeFrom": "example",
    "routeTo": "example",
    "footerLinks": [
      {
        "label": "example",
        "url": "example"
      }
    ],
    "notice": "example"
  },
  "accentContrast": 1,
  "included": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a color white text cannot be read on, a logo that is not a plain PNG or SVG, text over its length, or a link that is not https or mailto"
  }
}

DELETE /api/v1/admin/appearance

Return to the Farwing defaults: every logo, color, text and link is removed.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

{
  "appearance": {
    "companyName": "example",
    "accent": "example",
    "logo": "example",
    "logoDark": "example",
    "eyebrow": "example",
    "headline": "example",
    "subtext": "example",
    "linkLabel": "example",
    "linkUrl": "example",
    "cardTitle": "example",
    "cardSubtitle": "example",
    "globe": true,
    "routeFrom": "example",
    "routeTo": "example",
    "footerLinks": [
      {
        "label": "example",
        "url": "example"
      }
    ],
    "notice": "example"
  },
  "accentContrast": 1,
  "included": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

API keys

GET /api/v1/admin/api-keys

Every key on the server. Never a secret: a key is shown once, when it is made.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Each key has clients: the last version of the farwing command line and of Farwing Desktop it was used from, newest first. Empty for a key only used by scripts.

Success. 200.

The body is an array.

[
  {
    "id": "k7Qm2sLp9vX4aB1c",
    "name": "Rush delivery",
    "ownerId": "k7Qm2sLp9vX4aB1c",
    "ownerEmail": "[email protected]",
    "scopes": [
      "read"
    ],
    "createdAt": "2026-10-05T18:00:00Z",
    "revoked": true
  }
]

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

GET /api/v1/admin/api-keys/policy

How long a new key may live, and whether one may never expire.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

{
  "maxDays": 1,
  "allowNever": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

PUT /api/v1/admin/api-keys/policy

Change that. Keys already issued keep the expiry they were given.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "maxDays": 1,
  "allowNever": true
}

Success. 200.

{
  "maxDays": 1,
  "allowNever": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a value outside its allowed range"
  }
}

DELETE /api/v1/admin/api-keys/{id}

Revoke somebody else's key.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "ownerId": "k7Qm2sLp9vX4aB1c",
  "ownerEmail": "[email protected]",
  "scopes": [
    "read"
  ],
  "createdAt": "2026-10-05T18:00:00Z",
  "revoked": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Settings

GET /api/v1/admin/system

Version, uptime, disk, health checks and backups. A figure this platform cannot measure is absent rather than guessed.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

{
  "version": "example",
  "build": "example",
  "installId": "k7Qm2sLp9vX4aB1c",
  "startedAt": "2026-10-05T18:00:00Z",
  "uptimeSeconds": 1,
  "database": {
    "path": "projects/rush",
    "bytes": 1048576,
    "schemaVersion": 1
  },
  "disk": [
    {
      "name": "Rush delivery",
      "path": "projects/rush",
      "bytesFree": 1,
      "bytesTotal": 1
    }
  ],
  "checks": [
    {
      "name": "Rush delivery",
      "ok": true,
      "detail": "example"
    }
  ],
  "backups": [
    {
      "name": "Rush delivery",
      "bytes": 1048576,
      "modifiedAt": "2026-10-05T18:00:00Z"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

GET /api/v1/admin/system/logs

The audit trail as a text file. The process log goes to standard output, where the container runtime keeps it.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

JSON object.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Speed check

GET /api/v1/speedcheck

Past speed checks, and the weekly schedule.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only. A speed check measures what limits transfers on this server: the network, the processor, the staging disk, each storage location and the license's speed. It works on every plan, Free included. The reply is one page of checks (runs), how many match in all (total), the schedule, how many transfers are running now (transfersRunning), and how long a check usually takes in seconds (estimatedSeconds). from and to are inclusive. Without limit the page holds 50.

Parameters.

Success. 200.

{
  "runs": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "state": "active",
      "verdict": "example",
      "limiter": {},
      "receiveBps": 1,
      "sendBps": 1,
      "startedAt": "2026-10-05T18:00:00Z"
    }
  ],
  "total": 1,
  "schedule": {
    "enabled": true,
    "weekday": 1,
    "minute": 1,
    "addresses": [
      "example"
    ],
    "lastRunAt": "2026-10-05T18:00:00Z",
    "included": true
  },
  "transfersRunning": 1,
  "estimatedSeconds": 1,
  "places": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "title": "example",
      "path": "projects/rush",
      "role": "example",
      "region": "example"
    }
  ],
  "savedBucketIds": [
    "k7Qm2sLp9vX4aB1c"
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a time that is not RFC 3339, a page size below 1, or a page that starts before 0"
  }
}

POST /api/v1/speedcheck

Start a speed check.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only. Answers at once with the check in state running. It takes about two minutes, so read it again by its id to follow the progress and get the result. It writes test data to each location it times and slows live transfers while it runs. When transfers are running and confirmBusy is not true, nothing starts and the answer is 409; ask again with it set to go ahead. A check that is already running is returned instead of starting a second one.

Request body. JSON.

The body may be left out.

{
  "confirmBusy": true,
  "testSizeMb": 1,
  "bucketIds": [
    "k7Qm2sLp9vX4aB1c"
  ]
}

Success. 200.

{
  "outcome": {},
  "id": "k7Qm2sLp9vX4aB1c",
  "state": "active",
  "trigger": "example",
  "progressPercent": 1,
  "serverVersion": "example",
  "licensePlan": "example",
  "startedAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "conflict",
    "message": "transfers are running and `confirmBusy` was not set"
  }
}

PUT /api/v1/speedcheck/schedule

Turn the weekly speed check on or off, or change when it runs.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when turning it on, when this server's license does not include automation.

Administrators only. Send only what changes. Turning the schedule on needs the automation feature. Turning it off, or changing the day, time or addresses of one that is already on, does not, so a license that lapses never traps an administrator with a schedule they cannot edit. addresses are who the result is emailed to, up to 10.

Request body. JSON.

{
  "enabled": true,
  "weekday": 1,
  "minute": 1,
  "addresses": [
    "example"
  ]
}

Success. 200.

{
  "enabled": true,
  "weekday": 1,
  "minute": 1,
  "addresses": [
    "example"
  ],
  "lastRunAt": "2026-10-05T18:00:00Z",
  "included": true
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a day outside 0 to 6, a time outside 0 to 1439, an address that is not one, or more than 10 addresses"
  }
}

GET /api/v1/speedcheck/{id}

One speed check, with its progress while it runs.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only. While the check runs, progressPercent and progressStep say how far it has got. When it finishes, verdict says in one sentence what limits transfers on this server, and advice says what to do about it.

Parameters.

Success. 200.

{
  "outcome": {},
  "id": "k7Qm2sLp9vX4aB1c",
  "state": "active",
  "trigger": "example",
  "progressPercent": 1,
  "serverVersion": "example",
  "licensePlan": "example",
  "startedAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

DELETE /api/v1/speedcheck/{id}

Delete a finished speed check.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only. The row is removed. A check that is still running is refused, because it is still using the disks and it is what stops a second check from starting.

Parameters.

Success. 200.

The reply has no body.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

GET /api/v1/speedcheck/{id}/report.txt

A finished speed check as a text file.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only. The same words the screen shows, to paste into a support email, sent as an attachment named for the day the check started. A check that failed is reported with the reason.

Parameters.

Success. 200.

The body is plain text, not JSON.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

Email

GET /api/v1/admin/email/templates

Every email this server sends: its group, whether it is a security email, whether it is switched on, and which languages it has been written in.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only, on every plan. Reading works without a license so the editor can show what a license would add; included says whether this server may change anything, and freeMode says whether custom wording is saved but not being sent.

Success. 200.

{
  "included": true,
  "freeMode": true,
  "serverLanguage": "example",
  "languages": [
    "example"
  ],
  "layout": {
    "custom": true,
    "version": 1,
    "hasDraft": true
  },
  "kinds": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "group": "example",
      "title": "example",
      "about": "example",
      "security": true,
      "canDisable": true,
      "enabled": true,
      "custom": true,
      "hasDraft": true,
      "languages": [
        "example"
      ]
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

GET /api/v1/admin/email/templates/{kind}

One email in one language: its variables, its locked blocks, the built-in wording, the published version, the draft and the version history.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only, on every plan. lang picks the language and defaults to this server's. fallsBackTo names the language that is sent instead while this one has nothing of its own.

Parameters.

Success. 200.

{
  "kind": {
    "id": "k7Qm2sLp9vX4aB1c",
    "group": "example",
    "title": "example",
    "about": "example",
    "security": true,
    "canDisable": true,
    "enabled": true,
    "custom": true,
    "hasDraft": true,
    "languages": [
      "example"
    ]
  },
  "lang": "example",
  "variables": [
    {
      "group": "example",
      "vars": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "label": "example",
          "about": "example",
          "sample": "example",
          "kind": {}
        }
      ]
    }
  ],
  "requiredLocks": [
    "example"
  ],
  "lockWording": {},
  "versions": [
    {
      "version": 1,
      "at": "2026-10-05T18:00:00Z",
      "by": "example",
      "note": "The cut is in the folder."
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

PUT /api/v1/admin/email/templates/{kind}

Save the draft. Accepts wording with problems in it and hands the problems back, because the editor saves as you type.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Administrators only, and needs a license that includes branding. Publishing checks again and refuses; saving does not, so an administrator is never stopped mid-sentence.

Parameters.

Request body. JSON.

{
  "subject": [
    {}
  ],
  "previewText": [
    {}
  ],
  "plainText": "example",
  "doc": {
    "blocks": [
      {}
    ]
  }
}

Success. 200.

{
  "draft": {
    "draft": {
      "body": {
        "subject": [],
        "previewText": [],
        "plainText": "example",
        "doc": {}
      },
      "updatedAt": "2026-10-05T18:00:00Z"
    },
    "problems": [
      {
        "where": {},
        "blockId": "k7Qm2sLp9vX4aB1c",
        "message": "The cut is in the folder.",
        "suggestion": "example"
      }
    ]
  },
  "problems": [
    {
      "where": {},
      "blockId": "k7Qm2sLp9vX4aB1c",
      "message": "The cut is in the folder.",
      "suggestion": "example"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "the document is not a shape this server understands"
  }
}

DELETE /api/v1/admin/email/templates/{kind}/draft

Throw the draft away and go back to the published wording.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Parameters.

Success. 200.

{
  "kind": {
    "id": "k7Qm2sLp9vX4aB1c",
    "group": "example",
    "title": "example",
    "about": "example",
    "security": true,
    "canDisable": true,
    "enabled": true,
    "custom": true,
    "hasDraft": true,
    "languages": [
      "example"
    ]
  },
  "lang": "example",
  "variables": [
    {
      "group": "example",
      "vars": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "label": "example",
          "about": "example",
          "sample": "example",
          "kind": {}
        }
      ]
    }
  ],
  "requiredLocks": [
    "example"
  ],
  "lockWording": {},
  "versions": [
    {
      "version": 1,
      "at": "2026-10-05T18:00:00Z",
      "by": "example",
      "note": "The cut is in the folder."
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "licence_required",
    "message": "This server's license does not include email templates"
  }
}

POST /api/v1/admin/email/templates/{kind}/publish

Make the draft live, as a new numbered version with an optional note.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Administrators only, and needs a license that includes branding. Checked again here: a security email that has lost one of its locked blocks, an unknown variable, or a password link or code in a subject line is refused, however the request was made.

Parameters.

Request body. JSON.

{
  "note": "The cut is in the folder."
}

Success. 200.

{
  "kind": {
    "id": "k7Qm2sLp9vX4aB1c",
    "group": "example",
    "title": "example",
    "about": "example",
    "security": true,
    "canDisable": true,
    "enabled": true,
    "custom": true,
    "hasDraft": true,
    "languages": [
      "example"
    ]
  },
  "lang": "example",
  "variables": [
    {
      "group": "example",
      "vars": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "label": "example",
          "about": "example",
          "sample": "example",
          "kind": {}
        }
      ]
    }
  ],
  "requiredLocks": [
    "example"
  ],
  "lockWording": {},
  "versions": [
    {
      "version": 1,
      "at": "2026-10-05T18:00:00Z",
      "by": "example",
      "note": "The cut is in the folder."
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "the wording has a problem that must be fixed first"
  }
}

POST /api/v1/admin/email/templates/{kind}/reset

Make a draft from the built-in wording. Nothing is lost until it is published.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Parameters.

Request body. None.

Success. 200.

{
  "kind": {
    "id": "k7Qm2sLp9vX4aB1c",
    "group": "example",
    "title": "example",
    "about": "example",
    "security": true,
    "canDisable": true,
    "enabled": true,
    "custom": true,
    "hasDraft": true,
    "languages": [
      "example"
    ]
  },
  "lang": "example",
  "variables": [
    {
      "group": "example",
      "vars": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "label": "example",
          "about": "example",
          "sample": "example",
          "kind": {}
        }
      ]
    }
  ],
  "requiredLocks": [
    "example"
  ],
  "lockWording": {},
  "versions": [
    {
      "version": 1,
      "at": "2026-10-05T18:00:00Z",
      "by": "example",
      "note": "The cut is in the folder."
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "licence_required",
    "message": "This server's license does not include email templates"
  }
}

POST /api/v1/admin/email/templates/{kind}/restore

Make a draft from an earlier version. Body: {"version": 3}.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Parameters.

Request body. JSON.

{
  "version": 1
}

Success. 200.

{
  "kind": {
    "id": "k7Qm2sLp9vX4aB1c",
    "group": "example",
    "title": "example",
    "about": "example",
    "security": true,
    "canDisable": true,
    "enabled": true,
    "custom": true,
    "hasDraft": true,
    "languages": [
      "example"
    ]
  },
  "lang": "example",
  "variables": [
    {
      "group": "example",
      "vars": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "label": "example",
          "about": "example",
          "sample": "example",
          "kind": {}
        }
      ]
    }
  ],
  "requiredLocks": [
    "example"
  ],
  "lockWording": {},
  "versions": [
    {
      "version": 1,
      "at": "2026-10-05T18:00:00Z",
      "by": "example",
      "note": "The cut is in the folder."
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "licence_required",
    "message": "This server's license does not include email templates"
  }
}

POST /api/v1/admin/email/templates/{kind}/languages

Add a language to this email, copying the wording of another to translate. Body: {"lang": "pt-BR", "copyFrom": "en"}.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Parameters.

Request body. JSON.

{
  "lang": "example",
  "copyFrom": "example"
}

Success. 200.

{
  "kind": {
    "id": "k7Qm2sLp9vX4aB1c",
    "group": "example",
    "title": "example",
    "about": "example",
    "security": true,
    "canDisable": true,
    "enabled": true,
    "custom": true,
    "hasDraft": true,
    "languages": [
      "example"
    ]
  },
  "lang": "example",
  "variables": [
    {
      "group": "example",
      "vars": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "label": "example",
          "about": "example",
          "sample": "example",
          "kind": {}
        }
      ]
    }
  ],
  "requiredLocks": [
    "example"
  ],
  "lockWording": {},
  "versions": [
    {
      "version": 1,
      "at": "2026-10-05T18:00:00Z",
      "by": "example",
      "note": "The cut is in the folder."
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "not a language code such as en or pt-BR"
  }
}

DELETE /api/v1/admin/email/templates/{kind}/languages/{lang}

Remove a language. The email then falls back to this server's language.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Parameters.

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "group": "example",
  "title": "example",
  "about": "example",
  "security": true,
  "canDisable": true,
  "enabled": true,
  "custom": true,
  "hasDraft": true,
  "languages": [
    "example"
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "licence_required",
    "message": "This server's license does not include email templates"
  }
}

POST /api/v1/admin/email/templates/{kind}/enabled

Turn one email on or off. Body: {"enabled": false}.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API. This call can also answer 402 when this server's license does not include email templates.

Administrators only, and needs a license that includes branding. Security emails cannot be switched off; the notice about a new sign-in is the one exception, and it starts off.

Parameters.

Request body. JSON.

{
  "enabled": true
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "group": "example",
  "title": "example",
  "about": "example",
  "security": true,
  "canDisable": true,
  "enabled": true,
  "custom": true,
  "hasDraft": true,
  "languages": [
    "example"
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "this email cannot be switched off"
  }
}

POST /api/v1/admin/email/templates/{kind}/preview

Draw wording that has not been saved, with sample data, and get back the HTML, the plain text, the subject line and the preview line.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Administrators only, on every plan. data chooses the sample set: sample, long (long names and messages), empty (every optional field blank) or real (a recent package or user, named by realId). A preview never fails on a bad variable: it is drawn as the text that was typed and listed under problems.

Parameters.

Request body. JSON.

{
  "body": {
    "subject": [
      {}
    ],
    "previewText": [
      {}
    ],
    "plainText": "example",
    "doc": {
      "blocks": [
        {}
      ]
    }
  },
  "data": "example",
  "realId": "k7Qm2sLp9vX4aB1c"
}

Success. 200.