API reference

Base URL: https://app.trymaglev.com/api/v1. Use a bearer key for authenticated requests and Content-Type: application/json for JSON bodies. Keep secrets in your environment.

Download OpenAPI · Connect your agent · Errors and limits

This reference follows the public API 1.1.3 contract, with request and response annotations audited against source. Action schemas are listed in the action reference. Operational responses include a requestId; the OpenAPI endpoint returns the specification directly.

Endpoint families

All operations

Operation	What it does
`GET /health`	Service health, what an interview turn would actually do right now, and the endpoint families available.
`GET /openapi.json`	This document.
`GET /keys`	List the signed in organisation’s keys (browser session).
`POST /keys`	Issue a key. Sandbox keys are anonymous and live one day; live keys need a signed in organisation owner and live 90 days.
`DELETE /keys/{id}`	Revoke a key: the current key with a bearer token, or any of the organisation’s keys with an owner session.
`GET /me`	The calling key: mode, organisation kind and effective scopes.
`POST /auth/device`	Start a short-lived browser connection for Maglev CLI. No API key is created until an organization owner explicitly reviews and approves the matching terminal code.
`POST /auth/device/poll`	Check the same browser connection after its polling interval. Receives the same temporary API key after approval, including after a lost response.
`POST /auth/device/acknowledge`	Confirm that this terminal privately saved its own new key; requires that exact key as Bearer authorization.
`POST /auth/device/cancel`	Cancel an unacknowledged terminal request using its private deviceCode. Any issued temporary key is revoked atomically.
`POST /discover`	Rank interview backed capabilities for a request. Sandbox data is synthetic.
`POST /inspect`	One capability with its input schema and non binding pricing.
`POST /interviews`	Start a founder or manufacturer interview.
`GET /interviews/{id}`	Read an interview.
`POST /interviews/{id}/messages`	Answer the interviewer. Send the current version; 409 on conflict.
`POST /interviews/{id}/publish`	Publish the extracted record. Manufacturer records become self reported capabilities pending Maglev review; founder records become briefs.
`GET /capabilities`	The catalog visible to this key.
`GET /review-queue`	Self reported live capabilities awaiting Maglev review (Maglev session).
`POST /capabilities/{id}/review`	Publish a reviewed capability (Maglev session).
`POST /run`	Save a quote request against a capability. Requires Idempotency-Key. Never places an order.
`GET /runs`	Your saved runs.
`GET /runs/{id}`	One run.
`GET /factories`	List the factories Maglev works with. Never carries contact details; at most 50 per page.
`GET /factories/search`	Alias of GET /factories with q.
`GET /factories/{id}`	One factory by uuid or directory id. Customers receive selected manufacturing fields. Production keys with contacts:read also receive normalized business contacts; each such read is audited and capped at 300 per key per day. Raw directory, source, verification and interaction notes require a live internal maglev:* key.
`GET /factories/{id}/interactions`	Raw internal mail threads and call notes for a factory. Requires a live internal maglev:* key and is audited. Customer and sandbox keys cannot read this shared correspondence, including snippets and summaries; the legacy interactions:read scope does not grant access.
`GET /network/summary`	Counts of the network visible to this key: total, by process, by region, answered us, with certifications.
`GET /knowledge/search`	Full text search over explicitly published document revisions. Sandbox keys see published playbooks only. Internal categories and paths do not grant access; an empty published corpus returns no hits.
`GET /knowledge/documents`	One explicitly published document revision by exact repo path (production keys). Unpublished, changed and missing revisions return 404.
`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.
`GET /lifecycle/{stageId}`	One stage, with an example request body for its action kinds.
`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.
`POST /projects`	Open a project: the thing being built and the batch it is at.
`GET /projects`	Your newest 50 projects. Count is the number returned; no pagination is currently exposed.
`GET /projects/{id}`	One project with action counts by status.
`PATCH /projects/{id}`	Update project fields. Intake replaces the whole object; structured intent edits require expectedContextVersion.
`GET /projects/{id}/actions`	The newest 100 actions on a project, each paired with delivery summaries. No pagination is currently exposed.
`POST /projects/{id}/actions`	Request an action along the lifecycle. Available kinds return drafts; coordinated kinds create work items. Delivery drafts wait for approval.
`GET /actions`	Your newest 100 matching actions across projects, each paired with delivery summaries. No pagination is currently exposed.
`GET /actions/{id}`	One action with its output.
`GET /deliveries`	Your newest 100 matching outbound messages and their status. Count is the number returned; no pagination is currently exposed.
`GET /deliveries/{id}`	One delivery and its recoverable email dispatch receipt. Provider acceptance is not confirmation of recipient delivery.
`GET /deliveries/{id}/review`	Read the exact current draft recipient, copy list, subject, bodies and project fingerprint before approval. Live key only. Resolves the current supplier contact but approves and sends nothing. Show the complete result to the principal; echo reviewSha256 as expectedReviewSha256 only after their approval. Changed content, contact or project invalidates that approval.
`POST /deliveries/{id}/approve`	Approve the exact reviewed draft by sending expectedReviewSha256 from GET /deliveries/{id}/review after principal approval. A first approval without it returns approval_review_required (409); changed recipient, content or context returns approval_review_changed (409). Sandbox cannot send. The exact factory address, copy list, subject and bodies are frozen with a provider idempotency key before sending. Missing contact or stale RFQ context returns 409 without approval. Repeating approval returns the saved state; use retry for an unresolved dispatch. Email without configured transport remains approved and unsent. WeChat remains explicitly manual. Provider acceptance is not delivery or a supplier reply.
`POST /deliveries/{id}/retry`	Recover the same approved email dispatch. The exact payload and provider key are reused only after a 60-second worker lease and within 23 hours of the first attempt. Current caller and original approving keys, project context, payload and provider credential are rechecked. Expired deduplication or changed provider identity requires reconciliation, never blind resend. Legacy deliveries have no recoverable dispatch. Read GET /deliveries/{id} after an interrupted response.
`POST /deliveries/{id}/reject`	Reject a draft delivery; bodies are kept for the record. Once approval has claimed the draft, dispatch may already be in flight and rejection returns 409. This endpoint cannot cancel an approved send.
`GET /outbox`	Live manual outbox deliveries across owners (Maglev keys only). Uncertain provider dispatches and legacy resend_failed messages are excluded. Use only the frozen approved recipient.
`POST /deliveries/{id}/sent`	Record a live addressed manual outbox delivery as sent (Maglev keys only). Provider dispatches and unknown outcomes are rejected; never use this endpoint to bypass provider reconciliation.
`POST /shipping/estimate`	Deterministic freight and landed cost estimate, China to US. Chargeable weight, cost band per mode with its published source, fuel surcharge range, transit days, the duty stack as of Sep 2026, and a landed range. Every number carries a basis; nothing is binding.
`GET /shipping/track/{carrier}/{number}`	Track a shipment through DHL unified tracking or 17TRACK. Without a configured provider key the response is HTTP 200 with availability planned and the missing environment variable named.
`GET /shipping/providers`	Which tracking and rating providers are configured on this deployment (presence only, never values).
`POST /compliance/path`	Return a product-specific planning table of possible certification requirements and an optional draft explanation.
`POST /compliance/hts-candidates`	Return candidate tariff headings with reasoning and sources. No final classification is selected.
`GET /projects/{id}/engineering`	Read an owner-authorized engineering package
`POST /projects/{id}/engineering/preview`	Calculate an evidence-bound nonbinding price preview
`POST /projects/{id}/engineering/transfers`	Propose selected engineering files
`GET /projects/{id}/engineering/transfers/{transferId}`	Read a saved engineering transfer receipt
`POST /projects/{id}/engineering/transfers/{transferId}/files/{entryId}`	Retain one authorized engineering file
`GET /rfqs`	The managed supplier requests linked to your organization’s managed projects, newest first.
`GET /rfqs/{id}`	One managed supplier request with its per-factory invitations and the supplier quote versions actually linked to it.
`GET /pending-disclosures`	Read current and historical supplier file disclosures for your organization
`POST /pending-disclosures/{id}/revoke`	Take one outstanding engineering package back, and delete any grant it already caused.
`GET /actions/{id}/publication/review`	Read the exact scope that publication would disclose, and the digest over it
`POST /actions/{id}/publication/approval`	Ask the founder to approve disclosing this exact reviewed revision
`POST /actions/{id}/publication`	Publish a reviewed quote request to the selected suppliers

Response models