API

A blueprint is a desired project shape that Mobius can apply through the API: actions, toolkits, skills, agents, loops, and tables. Apply records a binding from each blueprint key to the Mobius resource it creates or adopts, so the same blueprint can be applied again without creating duplicates.

Use blueprints when an external system needs to provision the same Mobius setup for many projects. For one-off authoring, start in the Mobius app or with the normal mobius CLI resource commands.

What apply does

POST /v1/projects/{project_handle}/blueprints/apply accepts one desired resource graph and a mode:

Always run preview first. It catches missing references and name conflicts before the request changes the project.

Apply is idempotent, not a transaction across the whole blueprint. Mobius writes each resource together with its binding, but a failure in a later resource tier can leave earlier resources persisted. Re-apply the same blueprint after fixing the input; Mobius uses the bindings to converge instead of duplicating work.

Keys, names, and bindings

Every blueprint resource has a key. The key is local to the blueprint and is how other resources in the same apply refer to it:

{
  "agent": { "key": "triager" }
}

The created Mobius resource gets its normal ID, such as agt_... or loop_.... Mobius stores the mapping in a binding:

{
  "resource_type": "agent",
  "key": "triager",
  "resource_id": "agt_01..."
}

namespace, blueprint_key, and blueprint_version are optional provenance fields. Use them when one project may receive blueprints from more than one source, or when your own system needs to know which template version produced a resource.

Example blueprint

This blueprint creates one agent and one draft loop. Save it as triage-blueprint.json:

{
  "namespace": "acme",
  "blueprint_key": "github-triage",
  "blueprint_version": "2026-07-01",
  "mode": "preview",
  "resources": {
    "agents": [
      {
        "key": "triager",
        "name": "Triager",
        "model": "claude-sonnet-4-6",
        "system_prompt": "Classify inbound engineering issues for Acme."
      }
    ],
    "loops": [
      {
        "key": "triage_issues",
        "name": "triage-issues",
        "description": "Classify new GitHub issues and return a label.",
        "agent": {
          "key": "triager"
        },
        "status": "draft",
        "triggers": [
          {
            "key": "manual",
            "kind": "manual",
            "enabled": true
          }
        ],
        "steps": [
          {
            "id": "classify",
            "name": "Classify issue",
            "kind": "agent",
            "config": {
              "instructions": "Classify the issue from the run input. Return JSON with label, severity, and summary."
            }
          }
        ],
        "output": {
          "label": "${{ steps.classify.output.label }}",
          "severity": "${{ steps.classify.output.severity }}",
          "summary": "${{ steps.classify.output.summary }}"
        }
      }
    ]
  }
}

The loop lands as draft on purpose. Activate it only after a preview or test run shows the shape you expect.

From the app

The Mobius app does not apply blueprints yet. Use the CLI or HTTP API, then inspect the created agents, loops, tables, and bindings from their normal app pages.

From the CLI

Preview first:

mobius blueprints apply \
  --project platform \
  --file triage-blueprint.json

Expected output:

{
  "status": "previewed",
  "namespace": "acme",
  "blueprint_key": "github-triage",
  "blueprint_version": "2026-07-01",
  "changes": [
    {
      "resource_type": "agent",
      "key": "triager",
      "action": "created"
    },
    {
      "resource_type": "loop",
      "key": "triage_issues",
      "action": "created"
    }
  ],
  "bindings": []
}

Apply the same file by overriding the mode:

mobius blueprints apply \
  --project platform \
  --file triage-blueprint.json \
  --mode apply

Then list the bindings:

mobius blueprints list-bindings --project platform --namespace acme

Expected output:

{
  "items": [
    {
      "resource_type": "agent",
      "key": "triager",
      "resource_id": "agt_01...",
      "namespace": "acme",
      "blueprint_key": "github-triage",
      "blueprint_version": "2026-07-01"
    },
    {
      "resource_type": "loop",
      "key": "triage_issues",
      "resource_id": "loop_01...",
      "namespace": "acme",
      "blueprint_key": "github-triage",
      "blueprint_version": "2026-07-01"
    }
  ]
}

From the API

Use a project-scoped API key with permission to administer the resources the blueprint creates. The same request body works over HTTP:

curl -sS https://api.mobiusops.ai/v1/projects/platform/blueprints/apply \
  -H "Authorization: Bearer $MOBIUS_API_KEY" \
  -H "Content-Type: application/json" \
  --data @triage-blueprint.json

To apply after preview, send the same body with "mode": "apply":

jq '.mode = "apply"' triage-blueprint.json \
  | curl -sS https://api.mobiusops.ai/v1/projects/platform/blueprints/apply \
      -H "Authorization: Bearer $MOBIUS_API_KEY" \
      -H "Content-Type: application/json" \
      --data @-

List bindings with:

curl -sS "https://api.mobiusops.ai/v1/projects/platform/blueprints/bindings?namespace=acme" \
  -H "Authorization: Bearer $MOBIUS_API_KEY"

For exact schemas, see the interactive reference for blueprints.

FAQ

Does removing a resource from the blueprint delete it?

No. Removing a resource from the blueprint does not delete the Mobius resource. Blueprints converge desired resources that are present in the request. Delete resources explicitly when they should leave the project.

Can a blueprint update an unmanaged resource?

Only when Mobius can safely adopt a uniquely named resource. After adoption, the binding marks that resource as managed by the blueprint key. If a name matches more than one candidate, or if changing the resource would violate an immutability rule, apply returns a conflict.

Can I apply several blueprints to one project?

Yes, but use namespace and distinct resource keys so bindings stay explainable. If two blueprints try to manage the same underlying resource, the later apply may update it or return a conflict depending on the resource type and binding state.

Why did apply create some resources before failing?

Apply writes each resource and binding tier by tier. A later conflict can leave earlier tiers in place. Fix the request and re-apply; the existing bindings are what make the retry converge.

Next

• Loops explains the loop fields used inside blueprint loop resources.
• Agents explains model, toolkits, skills, and principal access.
• API Introduction covers authentication, project scope, errors, and pagination.