Projects and actions

A project holds what you are building. An action requests work on that project. A delivery is a message the work may produce for a factory. These are separate records with separate effects.

For a practical sequence from founder discovery to engineering scope, NDA review and a statement of work, follow scope the project and prepare agreements.

Discover what can run

curl --fail-with-body https://app.trymaglev.com/api/v1/lifecycle \
  -H "Authorization: Bearer $MAGLEV_API_KEY"
curl --fail-with-body https://app.trymaglev.com/api/v1/actions/kinds \
  -H "Authorization: Bearer $MAGLEV_API_KEY"

Read each kind’s inputSchema, outputSchema, availability and cost. The action reference documents all 23 published kinds, including NDA and SOW drafts, engineering plans, quote workflows, production readiness, shipping and compliance. The registry is the source of current action names. Do not invent an action name from a stage label.

• Available: an action can run and return a draft.
• Coordinated: work needs a Maglev person or partner. A queued work item is not a completed engineering deliverable.
• Planned: a place in the lifecycle, without an executable action yet.

Save the brief

curl --fail-with-body https://app.trymaglev.com/api/v1/projects \
  -H "Authorization: Bearer $MAGLEV_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Enclosure revision A","product":"Desk sensor enclosure","targetQuantity":100,"stage":"first_batch","markets":["US"],"intake":{"priorities":["dimensional quality","lead time","price"],"buildRegion":"US required","substitutions":"require approval","openQuestions":["Confirm drawing tolerances"]}}'

The response contains project.id. Keep that ID with your local brief and file manifest. intake preserves your extra context; it does not turn arbitrary text into a server-enforced budget or approval policy. Files remain local unless separately transmitted.

For quote preparation, preserve intent during factory selection: the automatic quote_request shortlist does not enforce geography or quality requirements stored in intake. Select reviewed factory UUIDs and copy applicable requirements into the action’s supported input fields.

quote_request uses confirmed current structured intent, otherwise the project target quantity or a single explicit band. Missing or unconfirmed current quantity produces missing-field questions without a model call or delivery. Alternative bands must include the confirmed current batch; planned pilots and forecasts are never ordered automatically. For other action kinds, read the current input schema and pass quantities explicitly. Check the quantity basis before moving from finished products to individual BOM parts.

GET /projects/{id} retrieves the project and action counts. PATCH /projects/{id} updates fields. Use the latest contextVersion as expectedContextVersion when updating. Structured manufacturing-intent changes require this guard. A changed project invalidates a prior RFQ for approval; old outputs remain historical.

Follow manage design revisions when a file, quantity or requirement changes. It covers intake replacement, concurrent writers, old action replays and pending delivery drafts.

Request one supported action

Prepare action.json using a kind and input schema returned by /actions/kinds. Then replace PROJECT_ID:

curl --fail-with-body https://app.trymaglev.com/api/v1/projects/PROJECT_ID/actions \
  -H "Authorization: Bearer $MAGLEV_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: enclosure-revision-a-action-001' \
  --data-binary @action.json

Inspect action.status, action.output, deliveries, task, note and next. The output is a draft for review. See idempotency and 409 conflicts before reusing a key.

The saved output has three fields: draft: true, note and result. The action reference describes the kind-specific value at action.output.result. For example, a readiness review’s items are at action.output.result.items. action.output can be null while running or after a failure; check the status and output before reading nested fields.

A timeout does not establish whether the request was saved. Retrieve the action before retrying. GET /projects/{id}/actions returns action entries with their associated deliveries; GET /actions/{id} retrieves one action.

Retrieve saved work

Action lists contain an entry for each action, not a flat list of action records:

{
  "actions": [
    {
      "action": { "id": "ACTION_ID", "status": "running", "output": null },
      "deliveries": []
    }
  ],
  "count": 1,
  "draft": true,
  "requestId": "REQUEST_ID"
}

This abbreviated example shows the nesting. Read IDs at actions[i].action.id. Delivery entries contain summaries such as ID, channel, status and subject; retrieve each delivery to read its full message. GET /actions/{id} also returns task, which is a summary or null.

Project lists return the newest 50 records. Action and delivery lists return at most the newest 100 matching records. Their count is the number returned, not a total across all saved work. These lists currently have no pagination. Keep project and action IDs locally; use a direct ID lookup for older records. The factory directory has its own pagination parameters.

Creating a project is not idempotent. Project updates replace the entire intake object; read and preserve the fields you need before updating it.

Read the action’s state

Newly requested work uses these states:

action.status	What happened	Next step
running	The request is saved; no final result has been recorded	Retrieve it again before starting replacement work
draft_ready	A result was generated without a task or delivery drafts	Review action.output.result and its evidence
awaiting_approval	The action produced delivery drafts	Read each delivery; dispatch needs the applicable scope and user authority
queued	A coordination task was created	Read task and track the work; the physical result is not complete
failed	A failure was recorded	Inspect the saved error and input before deciding on a new attempt

An identical replay returns HTTP 200 even when the action is still running or has failed. Check the record’s status rather than treating HTTP success as completed manufacturing. Later delivery activity may update the parent action to approved or sent; inspect each delivery for its actual state.

Review a delivery before approval

Use GET /deliveries/{id}/review or maglev deliveries review ID --json with a live key. Show the complete resolved recipient, copied recipients, subject, both bodies and project context to the principal.

After authorization, send its reviewSha256 as JSON expectedReviewSha256 to POST /deliveries/{id}/approve. Changed reviewed fields fail with a conflict before approval or sending. The delivery execution guide covers CLI/MCP commands, exact effects and recovery.

Read the dispatch receipt: ready is approved but unattempted, sending is leased, uncertain needs bounded same-dispatch recovery, and accepted means provider acceptance only. Missing email transport remains explicitly unsent. Sandbox cannot send. Approval does not sign, place an order or establish a production gate.

CLI coverage

The CLI supports projects, actions, delivery reads, the factory network, knowledge and lifecycle stages:

maglev projects create --input brief.json --json
maglev actions kinds --json
maglev actions request PROJECT_ID --input action.json --idempotency-key revision-a-action-001 --json
maglev actions get ACTION_ID --json
maglev deliveries get DELIVERY_ID --json

The default action timeout is four minutes. A timeout still requires checking saved state before retrying. CLI 0.6.14 and MCP 0.2.14 support the same explicit reviewed approval and recovery. The API reference lists these endpoint families separately.

Observe saved actions

Wait for an action with hosted CLI 0.6.14/MCP 0.2.14. The bounded read follows an existing running action and returns original evidence at draft, approval, coordination or failure states. It never recreates work, retries a write or grants approval. Native connector 0.1.6 includes the same tools. Reconnect or review a project upgrade when using an older installation.

Recovering a lost action ID

Recover a lost action ID is available in hosted CLI0.6.14/MCP0.2.14. It uses the original project, kind and idempotency key, and reads only recent saved work. A missing match does not establish absence or authorize a replacement. Native connector 0.1.6 includes the same CLI 0.6.14/MCP 0.2.14 tools; an older project may need a reviewed upgrade.