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

# API Overview

> Introduction to the Poesius REST API

## Base URL

```
https://poe.poesius.com/api/v1
```

## Main Endpoints

### Generate Slides from Document

**Endpoint**: `POST /slides/generate-from-doc`

Asynchronously generates slides from an uploaded document. Returns immediately with a presentation ID and status URL for polling.

<Card title="Learn More" icon="wand-magic-sparkles" href="/api/generate-slides">
  Detailed guide on generating slides from documents
</Card>

### Check Presentation Status

**Endpoint**: `GET /presentations/{presentation_id}`

Get the current status of a presentation, including slide count and download availability.

<Card title="Learn More" icon="circle-check" href="/api/check-status">
  How to check presentation status and poll for completion
</Card>

### Download Presentation

**Endpoints**:

* `GET /presentations/{presentation_id}/download` - Direct download (requires authentication)
* `GET /presentations/{presentation_id}/download-link` - Get shareable download link

Download the complete presentation as a PPTX file. The download-link endpoint returns a signed URL that can be shared or embedded.

<Card title="Learn More" icon="download" href="/api/download-presentation">
  Download your completed presentations
</Card>

### Template Management

**Endpoints**:

* `GET /templates/` - List all templates
* `GET /templates/default` - Get default template
* `POST /templates/default` - Set default template (request body with `template_id`)
* `POST /templates/{template_id}/set-default` - Set default template

Manage templates and set defaults for slide generation.

<Card title="Learn More" icon="palette" href="/api/templates">
  Template management and configuration
</Card>

## Authentication

All API requests require authentication. The API supports multiple authentication methods:

### API Key (Recommended)

The simplest method for programmatic access. Get your API key from `https://app.poesius.com`:

```http theme={null}
X-API-Key: pk_your_api_key_here
```

### OAuth 2.1 (Visual Login Required)

OAuth authentication requires a visual login flow through the web platform. This is **not suitable for headless automation** as it requires:

1. User interaction with a browser
2. Visual prompt/authorization screen
3. User consent and login

OAuth is primarily used for:

* Web applications that can redirect users to login
* MCP (Model Context Protocol) clients that support OAuth flows
* Applications requiring user consent screens

**Note**: OAuth cannot be used for fully automated scripts without user interaction.

### JWT Tokens

**Important**: JWT tokens are **not directly accessible** via the API. Authentication is managed by the frontend web application (`https://app.poesius.com`).

For programmatic access:

* Use **API Keys** (recommended for automation)
* Use **OAuth 2.1** if your application supports user login flows

The frontend handles JWT token management, session cookies, and user authentication. API clients should use API keys for server-to-server communication.

## Response Format

API responses are returned in JSON format with the following structure:

```json theme={null}
{
  "status": "pending|processing|completed|failed",
  "message": "Human-readable message",
  "data": {}
}
```

## Rate Limits

Rate limits apply to all API endpoints. Check your account limits in the web app at `https://app.poesius.com`.

## Next Steps

<Card title="Generate Slides" icon="wand-magic-sparkles" href="/api/generate-slides">
  Learn how to generate slides from documents
</Card>

<Card title="Examples" icon="code" href="/examples/rest-api">
  See complete REST API examples
</Card>