REST API

Authorization: Bearer lftsk_your_key_here

https://www.liftosaur.com/api/v1

GET /api/v1/programs

{
  "data": {
    "programs": [
      { "id": "abc123", "name": "5/3/1 BBB", "isCurrent": true },
      { "id": "def456", "name": "GZCLP", "isCurrent": false }
    ]
  }
}

GET /api/v1/programs/:id

{
  "data": {
    "id": "abc123",
    "name": "My Program",
    "text": "# Week 1\n## Day 1\nSquat / 3x5 / 135lb / progress: lp(5lb)",
    "isCurrent": true
  }
}

POST /api/v1/programs
Content-Type: application/json

{
  "name": "My Program",
  "text": "# Week 1\n## Day 1\nSquat / 3x5 / 135lb / progress: lp(5lb)"
}

{
  "data": {
    "id": "abc123",
    "name": "My Program",
    "text": "# Week 1\n## Day 1\nSquat / 3x5 / 135lb / progress: lp(5lb)"
  }
}

PUT /api/v1/programs/:id
Content-Type: application/json

{
  "text": "# Week 1\n## Day 1\nSquat / 5x5 / 185lb / progress: lp(10lb)",
  "name": "Updated Name"
}

{
  "data": {
    "id": "abc123",
    "name": "Updated Name",
    "text": "# Week 1\n## Day 1\nSquat / 5x5 / 185lb / progress: lp(10lb)",
    "isCurrent": true
  }
}

DELETE /api/v1/programs/:id

{
  "data": {
    "deleted": true
  }
}

GET /api/v1/history?limit=50&startDate=2026-01-01&endDate=2026-03-01

{
  "data": {
    "records": [
      {
        "id": 1,
        "text": "2026-03-01T10:00:00Z / program: \"5/3/1\" / dayName: \"Squat Day\" / week: 1 / dayInWeek: 1 / duration: 3600s / exercises: {\n  Squat, Barbell / 3x5 185lb / warmup: 1x5 95lb, 1x3 135lb / target: 3x5 185lb 120s\n  Leg Press / 3x10 200lb / target: 3x10 200lb 90s\n}"
      }
    ],
    "hasMore": false
  }
}

{
  "data": {
    "records": [...],
    "hasMore": true,
    "nextCursor": 42
  }
}

GET /api/v1/history/:id

{
  "data": {
    "id": 1,
    "text": "2026-03-01T10:00:00Z / program: \"5/3/1\" / dayName: \"Squat Day\" / exercises: {\n  Squat, Barbell / 3x5 185lb\n}"
  }
}

POST /api/v1/history
Content-Type: application/json

{
  "text": "2026-03-01T10:00:00Z / program: \"My Program\" / dayName: \"Day 1\" / week: 1 / dayInWeek: 1 / exercises: {\n  Squat / 3x5 135lb\n  Bench Press / 3x8 95lb\n}"
}

{
  "data": {
    "id": 1,
    "text": "2026-03-01T10:00:00Z / program: \"My Program\" / dayName: \"Day 1\" / week: 1 / dayInWeek: 1 / exercises: {\n  Squat / 3x5 135lb\n  Bench Press / 3x8 95lb\n}"
  }
}

PUT /api/v1/history/:id
Content-Type: application/json

{
  "text": "2026-03-01T10:00:00Z / exercises: {\n  Squat / 3x5 155lb\n}"
}

{
  "data": {
    "id": 1,
    "text": "2026-03-01T10:00:00Z / exercises: {\n  Squat / 3x5 155lb\n}"
  }
}

DELETE /api/v1/history/:id

{
  "data": {
    "deleted": true
  }
}

POST /api/v1/playground
Content-Type: application/json

{
  "programText": "# Week 1\n## Day 1\nSquat / 3x5 / 135lb / progress: lp(5lb)",
  "day": 1,
  "week": 1,
  "commands": [
    "complete_set(1, 1)",
    "complete_set(1, 2)",
    "complete_set(1, 3)",
    "finish_workout()"
  ]
}

{
  "data": {
    "workout": "2026-03-07T10:00:00Z / exercises: {\n  Squat, Barbell / 3x5 135lb / target: 3x5 135lb\n}",
    "updatedProgramText": "# Week 1\n## Day 1\nSquat / 3x5 / 140lb / progress: lp(5lb)"
  }
}

POST /api/v1/program-stats
Content-Type: application/json

{
  "programText": "# Week 1\n## Day 1\nSquat / 3x5 / 135lb\nBench Press / 3x8 / 95lb"
}

{
  "data": {
    "days": [
      { "name": "Day 1", "approxMinutes": 25, "workingSets": 6 }
    ],
    "totalWeeklySets": 6,
    "strengthSets": 3,
    "hypertrophySets": 3,
    "muscleGroups": [
      {
        "muscle": "Quads",
        "totalSets": 3,
        "strengthSets": 3,
        "hypertrophySets": 0,
        "frequencyPerWeek": 1,
        "exercises": [
          { "name": "Squat", "sets": 3, "isSynergist": false }
        ]
      },
      {
        "muscle": "Chest",
        "totalSets": 3,
        "strengthSets": 0,
        "hypertrophySets": 3,
        "frequencyPerWeek": 1,
        "exercises": [
          { "name": "Bench Press", "sets": 3, "isSynergist": false }
        ]
      }
    ]
  }
}

2026-03-01T10:00:00Z / program: "5/3/1" / dayName: "Push Day" / week: 1 / dayInWeek: 1 / duration: 3600s / exercises: {
  Bench Press, Barbell / 3x5 185lb, 1x3 185lb / warmup: 1x5 95lb, 1x3 135lb / target: 3x5 185lb 120s
  Overhead Press / 3x10 95lb / target: 3x10 95lb 60s
}

{
  "error": {
    "code": "parse_error",
    "message": "Failed to parse program",
    "details": [
      { "line": 3, "offset": 1, "message": "Unknown exercise: Barbell Curl" }
    ]
  }
}

{"maxWidth":1200,"url":"/doc","isLoggedIn":false}

{"doc":{"id":"api","title":"REST API","shortDescription":"Access your programs and workout history programmatically with the Liftosaur REST API.","order":1,"category":"Integrations","datePublished":"2026-03-07","dateModified":"2026-03-07"},"content":"## What is the Liftosaur API?\n\nLiftosaur has a REST API that lets you manage your programs and workout history programmatically. You can create programs, log workouts, simulate progressions, and pull stats - all from scripts, apps, or anything that can make HTTP requests.\n\nRequires a premium subscription.\n\n## Getting an API Key\n\n1. Open Liftosaur and go to **Settings**\n2. Tap **API Keys**\n3. Tap **Create API Key** and give it a name\n4. Copy the key - it starts with `lftsk_`\n\nKeep it secret. If you lose it, delete it and create a new one.\n\n## Authentication\n\nPass your API key as a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer lftsk_your_key_here\n```\n\nEvery request needs this header. Without it you'll get a `401` error.\n\n## Base URL\n\n```\nhttps://www.liftosaur.com/api/v1\n```\n\n## Endpoints\n\n### List Programs\n\n```\nGET /api/v1/programs\n```\n\nReturns all your programs with their IDs, names, and which one is currently active.\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"programs\": [\n { \"id\": \"abc123\", \"name\": \"5/3/1 BBB\", \"isCurrent\": true },\n { \"id\": \"def456\", \"name\": \"GZCLP\", \"isCurrent\": false }\n ]\n }\n}\n```\n\n### Get a Program\n\n```\nGET /api/v1/programs/:id\n```\n\nReturns the program's name and full source code in Liftoscript format. Use `id=current` to get the currently active program.\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"id\": \"abc123\",\n \"name\": \"My Program\",\n \"text\": \"# Week 1\\n## Day 1\\nSquat / 3x5 / 135lb / progress: lp(5lb)\",\n \"isCurrent\": true\n }\n}\n```\n\n### Create a Program\n\n```\nPOST /api/v1/programs\nContent-Type: application/json\n\n{\n \"name\": \"My Program\",\n \"text\": \"# Week 1\\n## Day 1\\nSquat / 3x5 / 135lb / progress: lp(5lb)\"\n}\n```\n\nThe `text` field must be valid Liftoscript. If there are syntax errors, you'll get a `422` response with line numbers and error messages.\n\n**Response (201):**\n\n```json\n{\n \"data\": {\n \"id\": \"abc123\",\n \"name\": \"My Program\",\n \"text\": \"# Week 1\\n## Day 1\\nSquat / 3x5 / 135lb / progress: lp(5lb)\"\n }\n}\n```\n\n### Update a Program\n\n```\nPUT /api/v1/programs/:id\nContent-Type: application/json\n\n{\n \"text\": \"# Week 1\\n## Day 1\\nSquat / 5x5 / 185lb / progress: lp(10lb)\",\n \"name\": \"Updated Name\"\n}\n```\n\n`name` is optional - if omitted, keeps the existing name. Use `id=current` to update the active program.\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"id\": \"abc123\",\n \"name\": \"Updated Name\",\n \"text\": \"# Week 1\\n## Day 1\\nSquat / 5x5 / 185lb / progress: lp(10lb)\",\n \"isCurrent\": true\n }\n}\n```\n\n### Delete a Program\n\n```\nDELETE /api/v1/programs/:id\n```\n\nCan't delete the currently active program.\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"deleted\": true\n }\n}\n```\n\n### List History\n\n```\nGET /api/v1/history?limit=50&startDate=2026-01-01&endDate=2026-03-01\n```\n\nQuery parameters (all optional):\n- `startDate` - ISO date or unix timestamp\n- `endDate` - ISO date or unix timestamp\n- `limit` - max records to return (default 50, max 200)\n- `cursor` - pagination cursor from previous response\n\nHistory records use Liftoscript Workouts - a compact, human-readable text format for workouts.\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"records\": [\n {\n \"id\": 1,\n \"text\": \"2026-03-01T10:00:00Z / program: \\\"5/3/1\\\" / dayName: \\\"Squat Day\\\" / week: 1 / dayInWeek: 1 / duration: 3600s / exercises: {\\n Squat, Barbell / 3x5 185lb / warmup: 1x5 95lb, 1x3 135lb / target: 3x5 185lb 120s\\n Leg Press / 3x10 200lb / target: 3x10 200lb 90s\\n}\"\n }\n ],\n \"hasMore\": false\n }\n}\n```\n\nWhen `hasMore` is `true`, use the `nextCursor` value as the `cursor` parameter in the next request:\n\n```json\n{\n \"data\": {\n \"records\": [...],\n \"hasMore\": true,\n \"nextCursor\": 42\n }\n}\n```\n\n### Get a History Record\n\n```\nGET /api/v1/history/:id\n```\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"id\": 1,\n \"text\": \"2026-03-01T10:00:00Z / program: \\\"5/3/1\\\" / dayName: \\\"Squat Day\\\" / exercises: {\\n Squat, Barbell / 3x5 185lb\\n}\"\n }\n}\n```\n\n### Create a History Record\n\n```\nPOST /api/v1/history\nContent-Type: application/json\n\n{\n \"text\": \"2026-03-01T10:00:00Z / program: \\\"My Program\\\" / dayName: \\\"Day 1\\\" / week: 1 / dayInWeek: 1 / exercises: {\\n Squat / 3x5 135lb\\n Bench Press / 3x8 95lb\\n}\"\n}\n```\n\nIf you include `program: \"Name\"`, the API looks up that program and links the workout to it - exercises get matched to their program counterparts, and the day name is filled in if you didn't specify one. If the program doesn't exist, you'll get a `400` error.\n\nYou can also create workouts without a program reference - just omit the `program` section.\n\n**Response (201):**\n\n```json\n{\n \"data\": {\n \"id\": 1,\n \"text\": \"2026-03-01T10:00:00Z / program: \\\"My Program\\\" / dayName: \\\"Day 1\\\" / week: 1 / dayInWeek: 1 / exercises: {\\n Squat / 3x5 135lb\\n Bench Press / 3x8 95lb\\n}\"\n }\n}\n```\n\n### Update a History Record\n\n```\nPUT /api/v1/history/:id\nContent-Type: application/json\n\n{\n \"text\": \"2026-03-01T10:00:00Z / exercises: {\\n Squat / 3x5 155lb\\n}\"\n}\n```\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"id\": 1,\n \"text\": \"2026-03-01T10:00:00Z / exercises: {\\n Squat / 3x5 155lb\\n}\"\n }\n}\n```\n\n### Delete a History Record\n\n```\nDELETE /api/v1/history/:id\n```\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"deleted\": true\n }\n}\n```\n\n### Playground\n\nSimulate a workout without saving anything. Use this to test program logic and progressions before committing.\n\n```\nPOST /api/v1/playground\nContent-Type: application/json\n\n{\n \"programText\": \"# Week 1\\n## Day 1\\nSquat / 3x5 / 135lb / progress: lp(5lb)\",\n \"day\": 1,\n \"week\": 1,\n \"commands\": [\n \"complete_set(1, 1)\",\n \"complete_set(1, 2)\",\n \"complete_set(1, 3)\",\n \"finish_workout()\"\n ]\n}\n```\n\nOnly `programText` is required. `day`, `week`, and `commands` are optional.\n\nAvailable commands:\n- `complete_set(exercise, set)` - mark a set done (1-indexed)\n- `change_weight(exercise, set, weight)` - e.g. `change_weight(1, 1, 185lb)`\n- `change_reps(exercise, set, reps)`\n- `change_rpe(exercise, set, rpe)`\n- `set_state_variable(exercise, name, value)`\n- `finish_workout()` - runs progression scripts, returns updated program text\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"workout\": \"2026-03-07T10:00:00Z / exercises: {\\n Squat, Barbell / 3x5 135lb / target: 3x5 135lb\\n}\",\n \"updatedProgramText\": \"# Week 1\\n## Day 1\\nSquat / 3x5 / 140lb / progress: lp(5lb)\"\n }\n}\n```\n\n`updatedProgramText` is only present when `finish_workout()` is included in the commands.\n\n### Program Stats\n\nGet stats for a program without saving it - workout duration estimates, weekly volume per muscle group, strength vs hypertrophy breakdown.\n\n```\nPOST /api/v1/program-stats\nContent-Type: application/json\n\n{\n \"programText\": \"# Week 1\\n## Day 1\\nSquat / 3x5 / 135lb\\nBench Press / 3x8 / 95lb\"\n}\n```\n\n**Response:**\n\n```json\n{\n \"data\": {\n \"days\": [\n { \"name\": \"Day 1\", \"approxMinutes\": 25, \"workingSets\": 6 }\n ],\n \"totalWeeklySets\": 6,\n \"strengthSets\": 3,\n \"hypertrophySets\": 3,\n \"muscleGroups\": [\n {\n \"muscle\": \"Quads\",\n \"totalSets\": 3,\n \"strengthSets\": 3,\n \"hypertrophySets\": 0,\n \"frequencyPerWeek\": 1,\n \"exercises\": [\n { \"name\": \"Squat\", \"sets\": 3, \"isSynergist\": false }\n ]\n },\n {\n \"muscle\": \"Chest\",\n \"totalSets\": 3,\n \"strengthSets\": 0,\n \"hypertrophySets\": 3,\n \"frequencyPerWeek\": 1,\n \"exercises\": [\n { \"name\": \"Bench Press\", \"sets\": 3, \"isSynergist\": false }\n ]\n }\n ]\n }\n}\n```\n\n## Liftoscript and Liftoscript Workouts\n\nPrograms use Liftoscript - a custom DSL for defining workout programs. It's not a standard format, so you'll need to learn the syntax to write valid programs. Check out the built-in program library for examples, or use the [MCP server](/docs/mcp) to let an AI assistant write programs for you.\n\nHistory records use Liftoscript Workouts - a compact text format for workouts. Here's what a record looks like:\n\n```\n2026-03-01T10:00:00Z / program: \"5/3/1\" / dayName: \"Push Day\" / week: 1 / dayInWeek: 1 / duration: 3600s / exercises: {\n Bench Press, Barbell / 3x5 185lb, 1x3 185lb / warmup: 1x5 95lb, 1x3 135lb / target: 3x5 185lb 120s\n Overhead Press / 3x10 95lb / target: 3x10 95lb 60s\n}\n```\n\n## Error Responses\n\nErrors come back as JSON with a status code, error code, and message:\n\n```json\n{\n \"error\": {\n \"code\": \"parse_error\",\n \"message\": \"Failed to parse program\",\n \"details\": [\n { \"line\": 3, \"offset\": 1, \"message\": \"Unknown exercise: Barbell Curl\" }\n ]\n }\n}\n```\n\nCommon status codes:\n- `401` - missing or invalid API key\n- `403` - no active subscription\n- `400` - invalid input (wrong program name, can't delete active program, etc.)\n- `404` - record or program not found\n- `422` - parse error (invalid Liftoscript or Liftoscript Workouts syntax)"}