Moves¶
A move of one organization to its own database, and back.
Ask for a move of an organization¶
POST /v1/moves
Makes a move request of one organization and its install command. Give the
organization's administrator the command (install.command) and the cabinet link
(portal_url): both are shown only in this answer. The runner checks that the
organization exists first, so the call takes up to a few seconds.
Body (application/json): CreateMove
| Field | Type | Description |
|---|---|---|
installation |
string | The installation; may be left out when the account has one. |
org |
integer, at least 1 | The organization's number. Give org or tenant. |
tenant |
string | The organization's uuid, when your tenants are uuids. |
require_approval |
boolean | Wait for approve after the check (default from the service's settings). |
customer_can_move_back |
boolean | Let the organization's administrator move back from the cabinet. |
callback_url |
string (uri) | Where this move's state changes are posted (else the account's receiver). |
external_ref |
string | Your own reference (a customer id), echoed in the move and its webhooks. |
customer_email |
string (email), up to 254 characters | The organization's administrator's address. It gets the alerts about their side only (agent_gone, customer_db_unreachable, extension_needed), on plans with alerts; your account's own addresses get every alert. |
Responses
| Status | Description | Body |
|---|---|---|
201 |
The move, with its install command and cabinet link. | Move |
400 |
BadRequest: A field is missing or wrong. | Error |
401 |
Unauthorized: No valid API key (or session). login_url is for the panel. |
Error |
429 |
TooMany: rate_limited: over the key's or the address's rate (see Rate limits); wait Retry-After seconds. |
Error |
402 |
PlanLimit: error starts with plan_limit:: the plan's organizations are all in use (a live move or at a customer). Upgrade, or move one back. |
Error |
403 |
Forbidden: The account is pending (account_pending, activated by us after "request access"), suspended, or the route is the owner's, or the key is read-only. |
Error |
404 |
NotFound: No such object in your account (another account's ids answer the same). | Error |
409 |
The organization has a live move already (id names it), or no database is connected yet. |
Error |
428 |
ConsentRequired: consent_required: a signed-in person has to accept new versions of the Terms first (panel sessions only). |
Error |
503 |
RunnerSilent: Your runner did not answer (it is down or not connected); see /v1/accounts/{a}/runners. |
Error |
List moves¶
GET /v1/moves
The account's moves, newest first (up to 200).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
installation |
query | string | Only this installation's. |
org |
query | integer, at least 1 | Only this organization's. |
state |
query | MoveState | |
q |
query | string | Matches the organization's number, its tenant or the external reference. |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The moves. | object |
400 |
BadRequest: A field is missing or wrong. | Error |
401 |
Unauthorized: No valid API key (or session). login_url is for the panel. |
Error |
429 |
TooMany: rate_limited: over the key's or the address's rate (see Rate limits); wait Retry-After seconds. |
Error |
A move's status¶
GET /v1/moves/{id}
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The move. | Move |
401 |
Unauthorized: No valid API key (or session). login_url is for the panel. |
Error |
429 |
TooMany: rate_limited: over the key's or the address's rate (see Rate limits); wait Retry-After seconds. |
Error |
404 |
NotFound: No such object in your account (another account's ids answer the same). | Error |
A move's events¶
GET /v1/moves/{id}/events
Its progress lines and state changes after after (a sequence number), up to 500.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | |
after |
query | integer, default 0 |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The events. | object |
401 |
Unauthorized: No valid API key (or session). login_url is for the panel. |
Error |
429 |
TooMany: rate_limited: over the key's or the address's rate (see Rate limits); wait Retry-After seconds. |
Error |
404 |
NotFound: No such object in your account (another account's ids answer the same). | Error |
A move's events as a stream¶
GET /v1/moves/{id}/stream
Server-sent events: event: status (data: {state, phase, progress, error, warning})
whenever the move changes, and one event per line of progress (event: its kind,
id: its sequence number, data: a MoveEvent). Reconnect with Last-Event-ID to go on
where it stopped. The stream ends when the move is in a final state.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | |
after |
query | integer | Start after this sequence number. |
Last-Event-ID |
header | string |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The stream. | text/event-stream |
401 |
Unauthorized: No valid API key (or session). login_url is for the panel. |
Error |
429 |
TooMany: rate_limited: over the key's or the address's rate (see Rate limits); wait Retry-After seconds. |
Error |
404 |
NotFound: No such object in your account (another account's ids answer the same). | Error |
The move's check report¶
GET /v1/moves/{id}/report
The full report of lokadb check -json (schema 1) on the organization's database. 404 before the check ran.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The report. | CheckReport |
401 |
Unauthorized: No valid API key (or session). login_url is for the panel. |
Error |
429 |
TooMany: rate_limited: over the key's or the address's rate (see Rate limits); wait Retry-After seconds. |
Error |
404 |
NotFound: No such object in your account (another account's ids answer the same). | Error |
Act on a move¶
POST /v1/moves/{id}/{action}
actions in the move says which are allowed now; any other answers 409.
- token: a new install command (the old token stops working);
- approve: let a checked move start (when require_approval);
- recheck: run the check again after a fix;
- retry: start a failed step again;
- cancel: stop before the move switches (the agent is revoked);
- move-back: bring the organization back to your database;
- portal: a new cabinet link (the old one stops working).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string | |
action (required) |
path | string: token, approve, recheck, retry, cancel, move-back, portal |
Responses
| Status | Description | Body |
|---|---|---|
200 |
The move after the action (install after token, portal_url after portal). |
Move |
401 |
Unauthorized: No valid API key (or session). login_url is for the panel. |
Error |
429 |
TooMany: rate_limited: over the key's or the address's rate (see Rate limits); wait Retry-After seconds. |
Error |
403 |
Forbidden: The account is pending (account_pending, activated by us after "request access"), suspended, or the route is the owner's, or the key is read-only. |
Error |
404 |
NotFound: No such object in your account (another account's ids answer the same). | Error |
409 |
Not allowed in the move's current state (state and a hint with the allowed actions). |
Error |