---
agentTools:
  projectIndex: https://elai.readme.io/llms.txt
---

# Retrieve an outline

Returns the outline with its drafts, including any chapters, speeches and quiz questions generated so far.

Returns the outline and everything generated onto it so far. `drafts[]` is the interesting part —
each entry carries either a `chapter` (title plus bullet points, which becomes a content slide) or
a `quiz` (which becomes a silent quiz slide), plus the `speech` written by
[Generate a script](https://elai.readme.io/reference/generate-outline-script).

`status` tells you how far along it is:

| `status`  | Meaning                       |
| :-------- | :---------------------------- |
| `outline` | Chapters exist, no speech yet |
| `script`  | Speeches have been generated  |

Draft `id` values are stable and are what you pass as `draftIds` to the speech and quiz endpoints,
so read the outline before targeting individual drafts.

# OpenAPI definition

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Elai Public API",
    "version": "1.0",
    "description": "Every endpoint below is served under `https://apis.elai.io/api/v1`.\n\n## Authentication\n\nSend your workspace API token as a bearer token on every request:\n\n```\nAuthorization: Bearer <your-api-token>\n```\n\nGenerate and rotate the token in the Elai web app under **Settings → API**, or through\n`POST /generateToken`. The token is scoped to one **workspace** and authenticates as that\nworkspace's admin user — it is not tied to an individual person, and it carries admin rights\ninside that workspace.\n\nA request with a missing, unknown or revoked token gets a bare `401` with no response body.\n\n> **Organizations on the Unlimited plan cannot use the API.** Their requests are rejected with the\n> same bare `401` as an invalid token, with nothing to distinguish the two. If a valid, freshly\n> generated token returns `401` on every endpoint, check the plan first.\n\n## Errors\n\nFailures carry a JSON body of the shape `{ \"message\": \"...\" }`. Validation failures on the newer\nendpoints may add an `errors` array naming the offending fields. `401` is the exception: it has no\nbody at all.\n\nBoth render endpoints are **fire-and-forget** — they queue work and return immediately, so a\n`200` means \"accepted\", not \"rendered\". Render failures surface only through the `video_error`\nwebhook, never as an HTTP error on the call that started the render.\n\n## Scope\n\nThis reference is generated from the running code rather than maintained by hand, so it cannot\nquietly fall behind the API it describes. It documents 96 operations across the\n`/api/v1` surface.\n\nEndpoints are grouped by subject in the sidebar. If something you need is missing, or an endpoint\ndoes not behave as described here, tell us.\n\n---\n\n_Generated from `chore/web-4760/api-v1-reference-build` at `5289745d` on 2026-09-04._"
  },
  "servers": [
    {
      "url": "https://apis.elai.io/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "bearer",
        "x-default": "SECRET_KEY"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the failure."
          }
        }
      },
      "Chapter": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 1024
          },
          "points": {
            "type": "array",
            "maxItems": 128,
            "items": {
              "type": "string",
              "maxLength": 1024
            }
          }
        }
      },
      "QuizSettings": {
        "type": "object",
        "description": "How future quiz generation should behave. Distinct from a draft's actual `quiz` object.",
        "properties": {
          "quizType": {
            "type": "string",
            "enum": [
              "single",
              "multiple",
              "true-false",
              "mixed"
            ]
          },
          "placement": {
            "type": "string",
            "enum": [
              "distributed",
              "end"
            ]
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "answersCount": {
            "type": "integer",
            "minimum": 2,
            "maximum": 6
          },
          "feedback": {
            "type": "boolean"
          }
        }
      },
      "OutlineDraft": {
        "type": "object",
        "description": "One unit of the outline. Carries either a `chapter` (becomes a content slide) or a `quiz` (becomes a silent quiz slide).",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Stable within the outline. Referenced by `draftIds` on the speech and quiz endpoints."
          },
          "chapter": {
            "$ref": "#/components/schemas/Chapter"
          },
          "quiz": {
            "type": "object",
            "description": "Generated question object. Shape matches the quiz API.",
            "additionalProperties": true
          },
          "speech": {
            "type": "string",
            "description": "Voice-over text. Written by generate-script, replaced by rewrite/regenerate-speech."
          },
          "thumbnail": {
            "type": "string"
          },
          "manually": {
            "type": "boolean",
            "description": "True when a human edited this draft, so regeneration can leave it alone."
          }
        }
      },
      "Outline": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "outline",
              "script"
            ],
            "description": "`outline` once chapters exist, `script` once speeches have been generated."
          },
          "source": {
            "type": "string",
            "enum": [
              "prompt",
              "summary",
              "pptx"
            ]
          },
          "drafts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OutlineDraft"
            }
          },
          "quizSettings": {
            "$ref": "#/components/schemas/QuizSettings"
          },
          "videoId": {
            "type": "string",
            "description": "Set when the outline was created from a video, or after a video has been built from it."
          },
          "hasConvertedVideo": {
            "type": "boolean"
          },
          "accountId": {
            "type": "string"
          },
          "userId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/outline/{outlineId}": {
      "get": {
        "operationId": "retrieve-outline",
        "summary": "Retrieve an outline",
        "description": "Returns the outline with its drafts, including any chapters, speeches and quiz questions generated so far.",
        "parameters": [
          {
            "name": "outlineId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Id of the outline."
          }
        ],
        "responses": {
          "200": {
            "description": "The outline.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Outline"
                }
              }
            }
          },
          "404": {
            "description": "No outline with that id in the caller's account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Outline not found"
                }
              }
            }
          }
        },
        "tags": [
          "Outline"
        ]
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "tags": [
    {
      "name": "Outline",
      "description": "The prompt-to-video flow: create an outline, generate chapters, script and quizzes, then build a video from it."
    }
  ],
  "_id": {
    "buffer": {
      "0": 106,
      "1": 154,
      "2": 229,
      "3": 101,
      "4": 201,
      "5": 178,
      "6": 243,
      "7": 252,
      "8": 223,
      "9": 58,
      "10": 69,
      "11": 151
    }
  }
}
````