# createArrangement

> Part of the MAP Audio Music API docs. Index of every page: https://map.audio/developers/music-api/llms.txt. OpenAPI document: https://map.audio/developers/music-api/openapi.json.

`POST https://api.map.audio/v1/arrangements`

Fit a cutdown or check a DJ set

Plan a render without rendering. `cutdown` fits one preset (from `source` or a stored `plan`) to a length in seconds as a DJ set over its variations; `set` checks a DJ set you wrote: references, variations, lengths and transitions. The answer is the set in preset references, its tempo and length, and each item's start in bars and seconds. It costs nothing; render the set with POST /v1/dj/set, or a cutdown as an item of POST /v1/renders.

Auth: `Authorization: Bearer` with an API key or a map.audio access token. MCP tool: `create_arrangement`.

## Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | object | no | The preset a cutdown fits; give `source` or `plan`. |
| `source.preset` | string | yes | A factory preset `pam:factory/<slug>`, or its bare slug. At most 200 characters. |
| `source.variation` | integer | no | A variation slot of the preset, numbered from 1; GET /v1/presets/{id} lists the slots it has. Default: its base state. From 1 to 16. |
| `plan` | string | no | A stored plan whose base preset and tempo a cutdown fits. Matches `^plan_`. |
| `cutdown` | object | no | Fit the preset to about this many seconds, as an opening, a main section and an ending over its variations. |
| `cutdown.seconds` | number | yes | From 5 to 300. |
| `set` | object | no | A DJ set to check: `queue` lists its items in play order, each naming a factory preset (`presetPath`), its variation (`variationIndex`, counted from 0), its length in `bars` and the `transition` into it. GET /v1/transition-presets lists the transitions and the set schema's definitions. |

## Example

```sh
curl -sS "https://api.map.audio/v1/arrangements" \
  -H "Authorization: Bearer $MAP_API_KEY" \
  -H "Map-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{"source":{"preset":"pam:factory/thaw"},"cutdown":{"seconds":30}}'
```

### Request: Fit Thaw to about 30 seconds

```json
{
  "source": {
    "preset": "pam:factory/thaw"
  },
  "cutdown": {
    "seconds": 30
  }
}
```

### Request: Check a three-preset set

```json
{
  "set": {
    "queue": [
      {
        "presetPath": "pam:factory/acid-sprinkle",
        "bars": 16
      },
      {
        "presetPath": "pam:factory/teknochonic",
        "variationIndex": 1,
        "bars": 16,
        "transition": {
          "preset": "blend",
          "bars": 8
        }
      },
      {
        "presetPath": "pam:factory/breakbeatrcool",
        "variationIndex": 2,
        "bars": 16,
        "transition": {
          "preset": "drop"
        }
      }
    ],
    "tempo": {
      "bpm": 124
    }
  }
}
```

### 200: Thaw fitted to 30.9 seconds

```json
{
  "object": "arrangement",
  "set": {
    "queue": [
      {
        "presetPath": "pam:factory/thaw",
        "variationIndex": 0,
        "bars": 4
      },
      {
        "presetPath": "pam:factory/thaw",
        "variationIndex": 3,
        "bars": 9,
        "transition": {
          "preset": "blend",
          "bars": 2
        }
      },
      {
        "presetPath": "pam:factory/thaw",
        "variationIndex": 5,
        "bars": 4,
        "transition": {
          "preset": "blend",
          "bars": 2
        }
      }
    ],
    "tempo": {
      "bpm": 132
    }
  },
  "seconds": 30.909,
  "bpm": 132,
  "bars": 17,
  "boundaries": [
    {
      "index": 0,
      "preset": "pam:factory/thaw",
      "variation": 1,
      "startBar": 0,
      "startSeconds": 0,
      "bars": 4
    },
    {
      "index": 1,
      "preset": "pam:factory/thaw",
      "variation": 4,
      "startBar": 4,
      "startSeconds": 7.273,
      "bars": 9
    },
    {
      "index": 2,
      "preset": "pam:factory/thaw",
      "variation": 6,
      "startBar": 13,
      "startSeconds": 23.636,
      "bars": 4
    }
  ]
}
```

### 400: Unknown transition preset

```json
{
  "error": {
    "type": "invalid_request",
    "code": "dj_unknown_transition_preset",
    "message": "Unknown transition preset swoosh; GET /v1/transition-presets lists the ones a render can use.",
    "param": "set.queue[1].transition.preset",
    "retryable": false,
    "jobId": null,
    "docUrl": "https://map.audio/developers/music-api/errors#dj_unknown_transition_preset",
    "requestId": "9a3f7c2e5b1d8f40-LHR"
  }
}
```

## Responses

- `200`: The arrangement.
- `400`: Unknown transition preset
- `default`: Any other error: `error.code` names it, `error.param` the field at fault, and `error.docUrl` its entry in the error catalogue.

## Errors

- [`terms_required`](https://map.audio/developers/music-api/errors#terms_required)
- [`preset_not_found`](https://map.audio/developers/music-api/errors#preset_not_found)
- [`preset_not_served`](https://map.audio/developers/music-api/errors#preset_not_served)
- [`variation_not_found`](https://map.audio/developers/music-api/errors#variation_not_found)
- [`not_found`](https://map.audio/developers/music-api/errors#not_found)
- [`dj_invalid_set`](https://map.audio/developers/music-api/errors#dj_invalid_set)
- [`dj_offline_unsupported`](https://map.audio/developers/music-api/errors#dj_offline_unsupported)
- [`dj_preset_missing`](https://map.audio/developers/music-api/errors#dj_preset_missing)
- [`dj_unknown_transition_preset`](https://map.audio/developers/music-api/errors#dj_unknown_transition_preset)
- [`invalid_request`](https://map.audio/developers/music-api/errors#invalid_request)
- [`unsupported_media_type`](https://map.audio/developers/music-api/errors#unsupported_media_type)
- [`payload_too_large`](https://map.audio/developers/music-api/errors#payload_too_large)
- [`idempotency_key_unsupported`](https://map.audio/developers/music-api/errors#idempotency_key_unsupported)