Docs
Log inStart free
API referenceProjects

Set the project's grooves

A project's GROOVES are synthesized loops, one per scene, that play on the PROJECT's musical clock (its tempo map): bar n is bar n in every scene, so neighbouring grooves stay in phase across a join a

nd a seam sound (PUT /scenes/{sceneId}/transition) lands on it. Each scene plays its own pick, else the project default. Patterns carry no tempo or key — the project grid wins.

One atomic update, applied in order: add_presets, upsert, remove, default_id, scenes, gain_db, enabled. Patterns are validated (voice, steps grammar, ranges) and refused with a message the author can act on.

PUT
/projects/{id}/groove

Authorization

bearerAuth
AuthorizationBearer <token>

Typecut API key. Generate one in app.typecut.ai → Settings → API keys. Send as Authorization: Bearer tc_live_….

In: header

Path Parameters

id*string
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/groove" \  -H "Content-Type: application/json" \  -d '{}'
{
  "data": {
    "groove": {
      "version": 1,
      "library": {
        "property1": {
          "name": "string",
          "pattern": {
            "bars": 1,
            "tracks": [
              {
                "voice": "kick",
                "steps": "x...x...x...x...",
                "notes": [
                  0
                ],
                "fill": "string",
                "octave": -2,
                "gain": 0,
                "pan": -1,
                "tone": 0,
                "duck": 0,
                "crush": {
                  "bits": 3,
                  "hold": 1
                }
              }
            ],
            "swing": 0,
            "res": 4,
            "seed": 0
          }
        },
        "property2": {
          "name": "string",
          "pattern": {
            "bars": 1,
            "tracks": [
              {
                "voice": "kick",
                "steps": "x...x...x...x...",
                "notes": [
                  0
                ],
                "fill": "string",
                "octave": -2,
                "gain": 0,
                "pan": -1,
                "tone": 0,
                "duck": 0,
                "crush": {
                  "bits": 3,
                  "hold": 1
                }
              }
            ],
            "swing": 0,
            "res": 4,
            "seed": 0
          }
        }
      },
      "defaultId": "string",
      "scenes": {
        "property1": {
          "patternId": "string",
          "fillIntoEnd": true
        },
        "property2": {
          "patternId": "string",
          "fillIntoEnd": true
        }
      },
      "gainDb": 0,
      "enabled": true
    },
    "grid": {
      "bpm": 0,
      "meter": 0,
      "key": "string",
      "originSec": 0
    },
    "scenes": [
      {
        "scene_id": "string",
        "chapter_id": "string",
        "start_sec": 0,
        "duration_sec": 0,
        "pattern_id": "string",
        "name": "string",
        "from": "scene",
        "fill_into_end": true,
        "render": {
          "src": "string",
          "duration": 0,
          "first_bar": 0,
          "trains": {
            "property1": [
              0
            ],
            "property2": [
              0
            ]
          },
          "marks": [
            {
              "name": "string",
              "t": 0
            }
          ]
        }
      }
    ],
    "presets": [
      {
        "id": "string",
        "name": "string",
        "note": "string"
      }
    ],
    "notes": [
      "string"
    ],
    "edit_version": 0
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}
{
  "error": {
    "type": "conflict",
    "code": "conflict",
    "message": "string",
    "current_version": 0,
    "expected_version": 0,
    "last_writer": {
      "label": "string",
      "kind": "editor",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "at": "string"
    }
  }
}

Read the project's grooves GET

A project's GROOVES are synthesized loops, one per scene, that play on the PROJECT's musical clock (its tempo map): bar n is bar n in every scene, so neighbouring grooves stay in phase across a join a

Read the project's tempo GET

The project's musical grid (settings.tempo): bpm, meter, key, where bar 1 falls, and tempo sections.