> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magna.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Schedule

> Create an unlock schedule for a token, with an optional cliff and one or more schedule pieces.

Create an unlock schedule for a token. A schedule is made of an optional
**cliff** plus one or more **pieces** that each release a portion of the
allocation, either as a one-off event or periodically.

**Route:** `POST /api/external/v1/schedules/create`

## Headers

| Header              | Required | Description                |
| ------------------- | -------- | -------------------------- |
| `Content-Type`      | Yes      | Must be `application/json` |
| `x-magna-api-token` | Yes      | Your Magna API token       |

## Body parameters

| Field           | Type           | Required | Description                           |
| --------------- | -------------- | -------- | ------------------------------------- |
| `tokenId`       | string (uuid)  | Yes      | The token this schedule belongs to    |
| `name`          | string \| null | No       | Display name                          |
| `description`   | string \| null | No       | Description                           |
| `unlockAtStart` | number         | No       | Portion unlocked immediately at start |
| `cliff`         | object \| null | No       | Cliff config — see below              |
| `roundingMode`  | enum           | No       | `FLOOR`                               |
| `pieces`        | array          | No       | Schedule pieces — see below           |

**`cliff`**

| Field      | Type           | Description                                |
| ---------- | -------------- | ------------------------------------------ |
| `value`    | number \| null | Portion released at the cliff              |
| `duration` | number         | Cliff length (in `period` units)           |
| `period`   | enum           | `HOUR` · `DAY` · `WEEK` · `MONTH` · `YEAR` |

**`pieces[]`**

| Field                        | Type           | Description                                                                               |
| ---------------------------- | -------------- | ----------------------------------------------------------------------------------------- |
| `type`                       | enum           | `PERIODIC` or `ONE_OFF`                                                                   |
| `name`                       | string \| null | Piece name                                                                                |
| `portion`                    | number \| null | Portion of the allocation this piece releases                                             |
| `startDelay`                 | object \| null | `{ value, period }` delay before the piece begins                                         |
| `oneOffPieceConfiguration`   | object \| null | For `ONE_OFF`: `{ offset: { value, period }, dayOfMonth }`                                |
| `periodicPieceConfiguration` | object \| null | For `PERIODIC`: `{ length: { value, period }, frequency: { value, period }, dayOfMonth }` |

## Request example

```sh theme={null}
curl -X POST https://app.magna.so/api/external/v1/schedules/create \
-H 'Content-Type: application/json' \
-H 'x-magna-api-token: YOUR_API_KEY' \
-d '{
  "tokenId": "tok...uuid",
  "name": "4y monthly, 1y cliff",
  "cliff": { "value": 0, "duration": 1, "period": "YEAR" },
  "roundingMode": "FLOOR",
  "pieces": [
    {
      "type": "PERIODIC",
      "portion": 1,
      "periodicPieceConfiguration": {
        "length": { "value": 3, "period": "YEAR" },
        "frequency": { "value": 1, "period": "MONTH" }
      }
    }
  ]
}'
```

## Response example

```json theme={null}
{
  "id": "sch...uuid",
  "key": "S-ABC123",
  "name": "4y monthly, 1y cliff",
  "description": null,
  "unlockAtStart": null,
  "cliff": { "value": 0, "duration": 1, "period": "YEAR" },
  "roundingMode": "FLOOR",
  "createdAt": "2024-04-15T21:26:21.000Z"
}
```