> For the complete documentation index, see [llms.txt](https://guide.plusai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.plusai.com/apis-for-presentations/presentation-agent-api.md).
# Presentation Agent API
{% hint style="info" %}
Presentation Agent API requires a **Pro or Team plan**. [Learn more about pricing](/plus-ai/plans-and-billing.md).
{% endhint %}
The **Plus AI Presentation Agent API** lets you generate and edit PowerPoint presentations programmatically over HTTP. Instead of calling a single render endpoint, you delegate the work to an autonomous AI agent: you describe what you want in natural language, and the agent plans the deck, writes the content, builds the slides, and returns a finished `.pptx` (and `.pdf`).
Working with the agent is a simple two-step flow:
1. **Start a session** — send a `POST` request with your prompt (and any optional files). The API responds immediately with a `sessionId` and a polling URL.
2. **Get the result** — poll the session until its status reaches a terminal state, then download the generated presentation.
Alternatively, you can supply a **webhook callback URL** when you create the session, and we'll notify you when the result is ready — no polling required.
### Highlights
* **Natural-language generation** — describe the presentation you want and the agent builds it end to end, from outline to finished slides.
* **Edit existing decks** — provide an existing PowerPoint file to have the agent revise, extend, restyle, or translate it rather than starting from scratch.
* **Bring your own content** — attach supporting files (spreadsheets, documents, images, and more) and the agent incorporates them into the presentation.
* **Choose your model** — select from a range of leading AI models to balance speed, cost, and quality.
* **Asynchronous by design** — kick off long-running jobs and either poll for progress or receive a webhook callback when the deck is ready.
* **Polished output** — download the result as both PowerPoint (`.pptx`) and PDF, plus a thumbnail preview.
* **Multilingual** — generate or translate presentations in the language of your choice.
### Working with files
The Presentation Agent can do more than generate decks from a blank slate. Using the **Files API**, you can give the agent a **starting presentation** to work from and **attachments** to pull content from — so the agent edits and fills in a real deck instead of creating one from scratch. This unlocks a powerful pattern: **keep a presentation as a reusable template and have the agent refresh it on a schedule with the latest data.** Of course, you can also omit the starting presentation to create something new.
#### How it works
1. **Upload your files.** Send each file to `PUT /r/v0/files/upload`. Each upload returns a file ID.
2. **Reference them when you start a session.** In your `POST /r/v0/agent/sessions` request:
* Set `pptxFileId` to the file ID of the presentation you want the agent to start from and edit.
* Add any supporting files to `attachments` as a list of `{ "fileId": "..." }`. The agent reads these and uses their content to fill in or update the deck.
3. **Get the result.** Poll the session (or use a webhook callback) and download the updated presentation.
The agent treats `pptxFileId` as the canvas to edit — preserving your branding, layout, and structure — and treats `attachments` as the source material to incorporate.
#### Example: refresh a weekly analytics report
Suppose you maintain a branded "Weekly Performance Review" deck and want to regenerate it every Monday with last week's numbers.
1. Upload your existing report and this week's data export:
```bash
# Upload the existing report (your template/starting point)
curl -X PUT "https://api.plusdocs.com/r/v0/files/upload" \
-H "Authorization: Bearer $PLUSAI_API_KEY" \
-F "file=@weekly-report.pptx"
# → { "fileId": "file_abc123", ... }
# Upload this week's analytics export
curl -X PUT "https://api.plusdocs.com/r/v0/files/upload" \
-H "Authorization: Bearer $PLUSAI_API_KEY" \
-F "file=@analytics-2026-05-25.xlsx"
# → { "fileId": "file_def456", ... }
```
2. Start a session that updates the report using the new data:
```bash
curl -X POST "https://api.plusdocs.com/r/v0/agent/sessions" \
-H "Authorization: Bearer $PLUSAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Update this weekly performance review with the figures from the attached analytics export. Refresh the charts and KPI numbers for the week of May 25, keep the existing layout and branding, and update the title slide date.",
"pptxFileId": "file_abc123",
"attachments": [{ "fileId": "file_def456" }]
}'
```
The agent opens your existing report, reads the spreadsheet, updates the relevant slides, and returns a finished deck — ready to download or deliver via your webhook.
#### More ideas
* **Monthly board deck** — keep a board-meeting template and attach the month's financials, product metrics, and a notes doc; have the agent populate each section.
* **Sales proposal from a template** — start from your standard pitch deck and attach a customer brief so the agent tailors it to a specific prospect.
* **Translate and localize** — provide an existing deck and ask the agent to produce a version in another language while preserving design.
* **Quarterly review from raw data** — attach CSV exports and a summary document and have the agent build out the data slides on top of your template.
## Authentication
To authenticate with the Presentations API, you must first generate an API key. You can [generate an API key here](https://app.plusdocs.com/api-settings). \
\
\&#xNAN;*Note: Only one active API key per user is currently allowed.*\
\
Once you have an API key, you can authenticate your requests to the presentations api using [HTTP Bearer authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/):
```
Authorization: Bearer {PLUSAI_API_KEY}
```
## Create and start an AI agent session
> Creates a new agent session, posts the initial prompt, and starts the\
> agent. Returns a polling URL to track progress.\
> \
> Optionally seeds the session with an existing PowerPoint file\
> (\`pptxFileId\`) and/or file attachments (\`attachments\[].fileId\`). File\
> IDs must reference files owned by the caller's organization (e.g.\
> uploaded via \`PUT /r/v0/files/upload\`).
```json
{"openapi":"3.1.0","info":{"title":"PlusAI REST API","version":"v0"},"tags":[{"name":"Presentation Agent","description":"Create and drive AI presentation agent sessions."}],"servers":[{"url":"https://api.plusdocs.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued for your Plus organization, sent as a bearer token."}},"schemas":{"CreateAgentSessionRequest":{"type":"object","properties":{"prompt":{"type":"string","description":"The initial instruction for the agent."},"pptxFileId":{"type":"string","description":"ID of an existing PowerPoint file (uploaded via the files API) to\nseed the session with. Must reference a `.pptx`/PowerPoint file.\n"},"language":{"type":"string","description":"Target language. Defaults to `auto`.","default":"auto"},"attachments":{"type":"array","description":"Files to attach to the initial message.","items":{"type":"object","properties":{"fileId":{"type":"string"}},"required":["fileId"]}},"callbackUrl":{"type":"string","format":"uri","description":"HTTPS URL invoked when the session changes state. Must be a public\nHTTPS address (no localhost/private IPs).\n"},"model":{"type":"string","description":"The model to use.","enum":["claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-haiku-4-5","gpt-5.4","gpt-5.4-nano","gpt-5.4-mini","gpt-5.5"]}},"required":["prompt"]},"CreateAgentSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string"},"pollingUrl":{"type":"string","format":"uri","description":"URL to poll for session state."}},"required":["sessionId","pollingUrl"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"PaymentRequiredError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"responses":{"BadRequest":{"description":"The request was malformed or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/r/v0/agent/sessions":{"post":{"operationId":"createAgentSession","tags":["Presentation Agent"],"summary":"Create and start an AI agent session","description":"Creates a new agent session, posts the initial prompt, and starts the\nagent. Returns a polling URL to track progress.\n\nOptionally seeds the session with an existing PowerPoint file\n(`pptxFileId`) and/or file attachments (`attachments[].fileId`). File\nIDs must reference files owned by the caller's organization (e.g.\nuploaded via `PUT /r/v0/files/upload`).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentSessionRequest"}}}},"responses":{"201":{"description":"Session created and started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentSessionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient AI agent credits for the billing cycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Get the current state of an agent session
> Returns the current status of an agent session. Poll this endpoint\
> until \`status\` reaches a terminal value. When the agent finishes,\
> \`pdfUrl\`, \`pptxUrl\`, and \`thumbnailUrl\` are populated with download URLs.
```json
{"openapi":"3.1.0","info":{"title":"PlusAI REST API","version":"v0"},"tags":[{"name":"Presentation Agent","description":"Create and drive AI presentation agent sessions."}],"servers":[{"url":"https://api.plusdocs.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued for your Plus organization, sent as a bearer token."}},"schemas":{"AgentSession":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string","enum":["READY","IDLE","RUNNING","PENDING_TOOL_CALLS","DONE","INTERRUPTED","FAILED"]},"pdfUrl":{"type":["string","null"],"format":"uri","description":"Download URL for the generated PDF (populated when finished)."},"pptxUrl":{"type":["string","null"],"format":"uri","description":"Download URL for the generated PPTX (populated when finished)."},"thumbnailUrl":{"type":["string","null"],"format":"uri","description":"Download URL for a thumbnail image (populated when finished)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["sessionId","status"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"responses":{"BadRequest":{"description":"The request was malformed or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/r/v0/agent/sessions/{sessionId}":{"get":{"operationId":"getAgentSession","tags":["Presentation Agent"],"summary":"Get the current state of an agent session","description":"Returns the current status of an agent session. Poll this endpoint\nuntil `status` reaches a terminal value. When the agent finishes,\n`pdfUrl`, `pptxUrl`, and `thumbnailUrl` are populated with download URLs.\n","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The current session state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSession"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Upload a file
> Uploads a file as \`multipart/form-data\`. The upload is validated and\
> accepted synchronously, then processed asynchronously.\
> \
> Constraints:\
> \- The request method must be \`PUT\`.\
> \- \`Content-Type\` must be \`multipart/form-data\`.\
> \- \`Content-Length\` is required (chunked transfer encoding is not\
> supported).\
> \- Maximum size is 125 MB.
```json
{"openapi":"3.1.0","info":{"title":"PlusAI REST API","version":"v0"},"tags":[{"name":"Files","description":"Upload, list, and delete user files."}],"servers":[{"url":"https://api.plusdocs.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key issued for your Plus organization, sent as a bearer token."}},"schemas":{"UploadAccepted":{"type":"object","properties":{"status":{"type":"string"},"uploadId":{"type":"string"},"message":{"type":"string"}},"required":["status","uploadId","message"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"UploadError":{"type":"object","description":"Error envelope returned by the file-upload endpoint.","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/r/v0/files/upload":{"put":{"operationId":"uploadFile","tags":["Files"],"summary":"Upload a file","description":"Uploads a file as `multipart/form-data`. The upload is validated and\naccepted synchronously, then processed asynchronously.\n\nConstraints:\n- The request method must be `PUT`.\n- `Content-Type` must be `multipart/form-data`.\n- `Content-Length` is required (chunked transfer encoding is not\n supported).\n- Maximum size is 125 MB.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload."}},"required":["file"]}}}},"responses":{"202":{"description":"File received; processing will begin shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"Method not allowed (must use PUT).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}},"411":{"description":"Content-Length header is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}},"413":{"description":"File exceeds the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}},"415":{"description":"Content-Type must be multipart/form-data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadError"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://guide.plusai.com/apis-for-presentations/presentation-agent-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.