POST /v1/organizations/migrate

If you started with flat projects directly under your org and want to adopt the sub-organization model, migrate them in one call instead of recreating anything. You send a mapping of project → child-org name; Layers creates the named child orgs and moves the mapped projects under them, atomically. You call this with your parent (org:admin) key, and it acts on your own org — there's no :orgId in the path.

Each distinct child-org name in the mapping becomes one new child org. Two projects mapped to the same name land under the same new child; two different names create two children.

Example

curl -X POST https://api.layers.com/v1/organizations/migrate \
  -H "Authorization: Bearer $PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "mapping": {
      "prj_13fd8406-387a-4472-b6a2-531860557a6e": "Acme Coffee",
      "prj_9b2c7d10-5e44-4a01-8f3a-2c1d6e7f8a90": "Wayne Labs"
    }
  }'

{
  "projectsMoved": 2,
  "childrenCreated": 2,
  "children": [
    {
      "id": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
      "name": "Acme Coffee",
      "projectIds": ["prj_13fd8406-387a-4472-b6a2-531860557a6e"]
    },
    {
      "id": "org_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Wayne Labs",
      "projectIds": ["prj_9b2c7d10-5e44-4a01-8f3a-2c1d6e7f8a90"]
    }
  ]
}

Field notes

• projectsMoved is the total count of projects relocated; childrenCreated is the number of new child orgs minted.
• children lists each created child with its new org_… id and the projectIds now under it. Persist the ids against your customer records.
• History stays with the parent. A migrated project's past credit events remain on the parent's ledger; only its future spend bills to the new child wallet.
• 30-day read grace. For 30 days after the move, your parent key can still read a migrated project, so dashboards and reconciliation don't break the moment you migrate. After that, reach the project through its child (the X-Layers-Organization header or a child key).

Errors

See also

• Organizations concept → migrating existing projects — when and why to migrate.
• Manage customers with sub-organizations — the full customer lifecycle.
• Allocate credits — fund the new children after migrating.