Skip to main content
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

HeaderRequiredDescription
Content-TypeYesMust be application/json
x-magna-api-tokenYesYour Magna API token

​
Body parameters

FieldTypeRequiredDescription
tokenIdstring (uuid)YesThe token this schedule belongs to
namestring | nullNoDisplay name
descriptionstring | nullNoDescription
unlockAtStartnumberNoPortion unlocked immediately at start
cliffobject | nullNoCliff config — see below
roundingModeenumNoFLOOR
piecesarrayNoSchedule pieces — see below
cliff
FieldTypeDescription
valuenumber | nullPortion released at the cliff
durationnumberCliff length (in period units)
periodenumHOUR · DAY · WEEK · MONTH · YEAR
pieces[]
FieldTypeDescription
typeenumPERIODIC or ONE_OFF
namestring | nullPiece name
portionnumber | nullPortion of the allocation this piece releases
startDelayobject | null{ value, period } delay before the piece begins
oneOffPieceConfigurationobject | nullFor ONE_OFF: { offset: { value, period }, dayOfMonth }
periodicPieceConfigurationobject | nullFor PERIODIC: { length: { value, period }, frequency: { value, period }, dayOfMonth }

​
Request example

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

{
  "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"
}