Set up a Twin headlessly
Connect sources, build definitions, decide proposals and read the definition inventory through the public operations, without the app.
An agent or script can take a Twin from connected sources to published
definitions using only the public operations: REST through the Twin gateway,
the twin command line, or the MCP tools named below. People still decide the
proposals that change business meaning.
The sequence is the same everywhere:
- check the organisation's connections;
- prepare a build (an authoring preparation);
- follow its run;
- decide the proposals it raises;
- read the definition inventory.
Every command below takes --assert-org <org> so it fails before acting on the
wrong organisation, and every change takes --allow-write.
Before you begin
- Sign in as an organisation admin with
twin login, or give your OAuth clienttwin.read,twin.writeandtwin.connections(see Operator setup). Builds, their runs and the definition inventory are organisation-admin operations; a member is refused with403. - Automated authoring must be enabled for your deployment
(
MLX_TWIN_AUTHORING_AUTOMATED_SELECTABLE). Where it is off, creating a preparation is refused with403 Automated Authoring Disabled; ask your MLX contact to enable it or to start the build for you. - Accepting a definition needs whoever the organisation's proposal policy allows. Definitions default to organisation admins.
1. Check the connections
| Operation | REST | MCP |
|---|---|---|
twin.connections.list | GET /api/twin/connections | twin_connections_list |
twin.connections.verify | POST /api/twin/connections/verify | twin_connections_verify |
A connection is usable when its state is ready. Verify asks for a real
connector check; do not infer readiness from saved configuration.
Adding a provider connection for the first time needs the provider's own consent screen, which today opens from the MLX app. Once a source is connected, everything below runs without the app.
2. Prepare a build
A preparation fixes what a build reads and which models it uses, then starts its run.
twin build authoring start --all-current --idempotency-key setup-2026-11 --assert-org <org> --allow-writeFor a connector with a reviewed catalogue, plan and apply its entries instead; no author model is called:
twin build catalogue plan --connector xero --assert-org <org> --json
twin build catalogue apply --connector xero --idempotency-key xero-2026-11 --assert-org <org> --allow-writeTo revise an earlier build, refine it with guidance:
twin build authoring refine <release-id> --prompt "Split revenue by region" --all-current --idempotency-key refine-1 --assert-org <org> --allow-write| Operation | REST |
|---|---|
createTwinAuthoringPreparation | POST /api/twin/authoring-preparations |
listTwinAuthoringPreparations | GET /api/twin/authoring-preparations |
getTwinAuthoringPreparation | GET /api/twin/authoring-preparations/{preparationId} |
cancelTwinAuthoringPreparation | POST /api/twin/authoring-preparations/{preparationId}/cancel |
Reuse the same idempotency key when you retry: a repeated request returns the same preparation instead of starting a second build.
3. Follow the run
twin build watch <preparation-or-run-id> --assert-org <org>
twin build inspect <preparation-or-run-id> --assert-org <org> --json| Operation | REST |
|---|---|
listTwinAuthoringRuns | GET /api/twin/authoring-runs |
getTwinAuthoringRun | GET /api/twin/authoring-runs/{runId} |
listTwinAuthoringArtifacts | GET /api/twin/authoring-runs/{runId}/artifacts |
cancelTwinAuthoringRun | POST /api/twin/authoring-runs/{runId}/cancel |
The artifact list is metadata only. Raw build artifacts (model exchanges and SQL) stay in the app for administrators.
4. Decide the proposals
A finished build raises definition proposals. Nothing it built is installed or activated until one is accepted.
twin proposals --kind definition --json
twin proposals show <proposal-id> --json
twin proposals accept <proposal-id> --allow-write
twin proposals decline <proposal-id> --note "wrong grain" --allow-write
twin proposals undo <proposal-id> --allow-write
twin proposals retire <proposal-id> --note "replaced by sales-invoices" --allow-write| Operation | REST |
|---|---|
twin.proposals.list | GET /api/twin/proposals |
twin.proposals.get | GET /api/twin/proposals/{proposalId} |
twin.proposals.decide | POST /api/twin/proposals/{proposalId}/decision |
twin.proposals.undo | POST /api/twin/proposals/{proposalId}/undo |
twin.proposals.retire | POST /api/twin/proposals/{proposalId}/retire |
Show the person the proposal's title, summary and evidence, and decide only on their explicit answer. Review proposals explains the decisions and who may make them.
5. Read the definition inventory
twin build inventory --assert-org <org> --limit 100 --json
twin build explain <view-version-id-or-slug> --assert-org <org> --jsonThe inventory (listTwinLogicProducts, GET /api/twin/logic/products) lists
each admitted definition with its installation, activation and any known
routing blocker. When a definition is active, ask a question against it with
twin_query, the REST query operation or twin query.