Lifecycle
Base URL: https://app.trymaglev.com/api/v1. All endpoint families.
GET /lifecycle
Section titled “GET /lifecycle”The hardware lifecycle as Maglev’s playbooks define it: 35 stages in six phases, each with inputs, outputs, Maglev’s role, the action kinds that run it, and its availability today.
Required scope: lifecycle:read.
Authentication: bearer key.
200 response schema
{ "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/Stage" } }, "counts": { "type": "object", "properties": { "available": { "type": "integer" }, "coordinated": { "type": "integer" }, "planned": { "type": "integer" } } }, "total": { "type": "integer", "description": "Length of stages, which is every stage in the lifecycle. This route does not paginate" }, "note": { "type": "string", "description": "That availability is read from the action registry on each request, so a stage can change between calls" }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.
GET /lifecycle/{stageId}
Section titled “GET /lifecycle/{stageId}”One stage, with an example request body for its action kinds.
Required scope: lifecycle:read.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
stageId |
path | Yes |
200 response schema
{ "type": "object", "properties": { "stage": { "$ref": "#/components/schemas/Stage" }, "howToRequest": { "type": "object", "properties": {} }, "note": { "type": "string", "description": "The same note GET /lifecycle carries: availability is read from the action registry on each request" }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.
GET /actions/kinds
Section titled “GET /actions/kinds”Every action kind with its JSON schema for input and output, availability and stage ids. Also listed under x-action-kinds in this document.
Required scope: lifecycle:read.
Authentication: bearer key.
200 response schema
{ "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "availability": { "type": "string" }, "stageIds": { "type": "array", "items": { "type": "string" } }, "cost": { "type": "string" }, "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" } }, "required": [ "kind", "name", "description", "availability", "stageIds", "cost", "inputSchema", "outputSchema" ] } }, "count": { "type": "integer" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "kinds", "count", "note", "requestId" ]}Errors: 401 Invalid key or missing sign-in; 403 Insufficient access; 429 Rate limit reached; 500 Server failure. See recovery guidance.