> 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/api-reference/presentation-agent.md).

# Presentation Agent

Create and drive AI presentation agent sessions.

## 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 in the caller's organization that the caller\
> owns or that are shared with one of their teams (e.g. uploaded via\
> \`PUT /r/v0/files/upload\`); other files are reported as not found.<br>

```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` file (legacy\n`.ppt` files aren't supported).\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-fable-5","claude-opus-5-5","claude-opus-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-5-5","claude-sonnet-5","claude-sonnet-4-6","claude-haiku-4-5","gpt-5.4","gpt-5.4-nano","gpt-5.4-mini","gpt-5.4-pro","gpt-5.5","gpt-5.5-pro","gpt-5.6-sol","gpt-5.6-terra","gpt-5.6-luna","@cf/moonshotai/kimi-k2.7-code"]}},"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 in the caller's organization that the caller\nowns or that are shared with one of their teams (e.g. uploaded via\n`PUT /r/v0/files/upload`); other files are reported as not found.\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.\
> \
> A session is a conversation: its first prompt is turn 0, and each\
> message posted with \`POST /r/v0/agent/sessions/{sessionId}/messages\`\
> starts the next turn. \`status\`, \`lastAssistantMessage\`,\
> \`statusMessage\`, \`stalled\`, \`turnCreditsUsed\` and \`turnPptxUrl\` all\
> describe the current \`turn\`.\
> \
> \*\*Polling a turn.\*\* After posting a message that returned turn \`N\`,\
> poll until \`turn\` equals \`N\` and \`status\` is \`IDLE\`, \`FAILED\` or\
> \`INTERRUPTED\`, or until \`stalled\` is \`true\`. The new turn is recorded\
> before the message is acknowledged, so a poll never reports the\
> previous turn's result as the new turn's.\
> \
> Any member of the session's organization can read it; only the user\
> who created it can continue or interrupt it.<br>

```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","description":"The status of the current turn: `READY`, `RUNNING` and\n`PENDING_TOOL_CALLS` are in progress; `IDLE` means the turn\nfinished and the session is waiting for the next message.\n","enum":["READY","IDLE","RUNNING","PENDING_TOOL_CALLS","DONE","INTERRUPTED","FAILED"]},"turn":{"type":"integer","minimum":0,"description":"The conversation turn the session is on: 0 for the prompt it was\ncreated with, then one more for each message posted to it.\n"},"lastAssistantMessage":{"type":["string","null"],"description":"The agent's latest reply in the current turn, once it has ended. Null for sessions not created through this API (e.g. the web app's or the PowerPoint add-in's chats)."},"statusMessage":{"type":["string","null"],"description":"A description of the current status, e.g. why the turn failed."},"stalled":{"type":"boolean","description":"The current turn can no longer finish (it never started, or stopped\nmaking progress). Stop polling it; posting a new message replaces\nthe stalled turn.\n"},"turnCreditsUsed":{"type":["number","null"],"description":"AI agent credits the current turn has used so far."},"turnPptxUrl":{"type":["string","null"],"format":"uri","description":"Download URL for the presentation as of the end of the current\nturn (populated once the turn is finished). `pptxUrl` is always the\nlatest version.\n"},"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","turn","stalled"]},"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\nA session is a conversation: its first prompt is turn 0, and each\nmessage posted with `POST /r/v0/agent/sessions/{sessionId}/messages`\nstarts the next turn. `status`, `lastAssistantMessage`,\n`statusMessage`, `stalled`, `turnCreditsUsed` and `turnPptxUrl` all\ndescribe the current `turn`.\n\n**Polling a turn.** After posting a message that returned turn `N`,\npoll until `turn` equals `N` and `status` is `IDLE`, `FAILED` or\n`INTERRUPTED`, or until `stalled` is `true`. The new turn is recorded\nbefore the message is acknowledged, so a poll never reports the\nprevious turn's result as the new turn's.\n\nAny member of the session's organization can read it; only the user\nwho created it can continue or interrupt it.\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"}}}}}}}}}
```

## Continue an agent session with another prompt

> Posts a follow-up prompt to an existing session, which starts the\
> session's next turn and runs the agent on it. The agent keeps the\
> conversation so far and edits the session's presentation in place.\
> Poll the returned \`pollingUrl\` (the same URL as at creation) until\
> \`turn\` equals the returned \`turn\` and \`status\` is \`IDLE\`, \`FAILED\` or\
> \`INTERRUPTED\`, or until \`stalled\` is \`true\`.\
> \
> Only the user who created the session can continue it. A turn still\
> in progress must finish, or be stopped with\
> \`POST /r/v0/agent/sessions/{sessionId}/interrupt\`, before the next\
> one can start (\`409 AGENT\_BUSY\`).\
> \
> Send an \`Idempotency-Key\` header to retry safely: a retry with the\
> same key after the message was accepted returns the same turn and\
> doesn't start another.<br>

```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":{"SendAgentSessionMessageRequest":{"type":"object","properties":{"prompt":{"type":"string","description":"The follow-up instruction for the agent."},"attachments":{"type":"array","description":"Files to attach to the message, as for `POST /r/v0/agent/sessions`.\n","items":{"type":"object","properties":{"fileId":{"type":"string"}},"required":["fileId"]}},"callbackUrl":{"type":"string","format":"uri","description":"HTTPS URL invoked when this turn ends, replacing the session's\ncallback URL. Must be a public HTTPS address (no localhost/private\nIPs).\n"},"expectedTurn":{"type":"integer","minimum":0,"description":"The session's `turn` the caller last saw. The message is refused\nwith `409 CONVERSATION_ADVANCED` if the session has moved on.\n"}},"required":["prompt"]},"SendAgentSessionMessageResponse":{"type":"object","properties":{"sessionId":{"type":"string"},"turn":{"type":"integer","description":"The turn this message started. Poll until the session reports it."},"pollingUrl":{"type":"string","format":"uri","description":"URL to poll for session state (the same for every turn)."}},"required":["sessionId","turn","pollingUrl"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"AgentSessionRefusal":{"type":"object","description":"Why the session didn't accept the message. Nothing was changed.","properties":{"code":{"type":"string","enum":["AGENT_BUSY","CONVERSATION_ADVANCED","SESSION_NOT_CONTINUABLE","CONTEXT_OVERFLOW","INSUFFICIENT_AGENT_CREDITS","NOT_ORG_MEMBER","PRESENTATION_EDIT_FORBIDDEN","SESSION_EXPIRED","INVALID_ATTACHMENT_KEY","ATTACHMENT_FAILED","PDF_PAGE_LIMIT","ORG_ACCESS_UNVERIFIED","TURN_START_FAILED"]},"message":{"type":"string"},"turn":{"type":"integer","description":"The session's current turn."},"reason":{"type":"string","description":"For `SESSION_NOT_CONTINUABLE` and `SESSION_EXPIRED`, why the\nconversation can't continue (e.g. `agent`, `model_retired`, `age`, `turns`).\n"},"staleAt":{"type":["string","null"],"format":"date-time","description":"`AGENT_BUSY` only: when the running turn counts as stalled, after\nwhich a new message replaces it.\n"},"interruptUrl":{"type":"string","format":"uri","description":"`AGENT_BUSY` only: the URL that stops the running turn."}},"required":["code","message"]}},"responses":{"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/{sessionId}/messages":{"post":{"operationId":"sendAgentSessionMessage","tags":["Presentation Agent"],"summary":"Continue an agent session with another prompt","description":"Posts a follow-up prompt to an existing session, which starts the\nsession's next turn and runs the agent on it. The agent keeps the\nconversation so far and edits the session's presentation in place.\nPoll the returned `pollingUrl` (the same URL as at creation) until\n`turn` equals the returned `turn` and `status` is `IDLE`, `FAILED` or\n`INTERRUPTED`, or until `stalled` is `true`.\n\nOnly the user who created the session can continue it. A turn still\nin progress must finish, or be stopped with\n`POST /r/v0/agent/sessions/{sessionId}/interrupt`, before the next\none can start (`409 AGENT_BUSY`).\n\nSend an `Idempotency-Key` header to retry safely: a retry with the\nsame key after the message was accepted returns the same turn and\ndoesn't start another.\n","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A client-generated key for this message (e.g. a UUID), reused on\nretries. 1 to 255 letters, digits, `.`, `_`, `:` or `-`. Without\none, every request is a new message.\n","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAgentSessionMessageRequest"}}}},"responses":{"202":{"description":"Message accepted; the new turn has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAgentSessionMessageResponse"}}}},"400":{"description":"The request is invalid, or an attachment can't be used\n(`INVALID_ATTACHMENT_KEY`, `ATTACHMENT_FAILED`, `PDF_PAGE_LIMIT`).\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/AgentSessionRefusal"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient AI agent credits for the billing cycle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionRefusal"}}}},"403":{"description":"The caller may no longer use the session's organization\n(`NOT_ORG_MEMBER`) or edit its presentation\n(`PRESENTATION_EDIT_FORBIDDEN`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionRefusal"}}}},"404":{"description":"Session not found, or not created by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The session can't take this message now:\n- `AGENT_BUSY`: a turn is still in progress. Wait for it to end,\n  or stop it with `interruptUrl`, then post again. `staleAt` is\n  when the running turn counts as stalled, after which a new\n  message replaces it.\n- `CONVERSATION_ADVANCED`: `expectedTurn` is behind the session's\n  `turn`.\n- `SESSION_NOT_CONTINUABLE` (see `reason`) or `CONTEXT_OVERFLOW`:\n  the conversation can't continue; create a new session.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionRefusal"}}}},"410":{"description":"`SESSION_EXPIRED`: the conversation is too old or has too many\nturns (see `reason`); create a new session.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionRefusal"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"A temporary failure (`ORG_ACCESS_UNVERIFIED`,\n`TURN_START_FAILED`); retry with the same `Idempotency-Key`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionRefusal"}}}}}}}}}
```

## Stop the turn an agent session is working on

> Stops the session's current turn, and any sub-agents working on it,\
> if it is still in progress. The session then reports \`INTERRUPTED\`\
> and accepts the next message. Pass \`expectedTurn\` so a late request\
> can't stop a newer turn.\
> \
> Only the user who created the session can interrupt it.<br>

```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":{"InterruptAgentSessionRequest":{"type":"object","properties":{"expectedTurn":{"type":"integer","minimum":0,"description":"Stop only this turn. Without it, whichever turn is in progress is\nstopped.\n"}}},"InterruptAgentSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string"},"turn":{"type":"integer","description":"The turn that was stopped."},"status":{"type":"string","enum":["INTERRUPTED"]}},"required":["sessionId","turn","status"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"AgentSessionNotActive":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_ACTIVE"]},"message":{"type":"string"},"turn":{"type":"integer","description":"The session's current turn."},"status":{"type":"string","description":"The session's status."}},"required":["code","message","turn","status"]}},"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/{sessionId}/interrupt":{"post":{"operationId":"interruptAgentSession","tags":["Presentation Agent"],"summary":"Stop the turn an agent session is working on","description":"Stops the session's current turn, and any sub-agents working on it,\nif it is still in progress. The session then reports `INTERRUPTED`\nand accepts the next message. Pass `expectedTurn` so a late request\ncan't stop a newer turn.\n\nOnly the user who created the session can interrupt it.\n","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterruptAgentSessionRequest"}}}},"responses":{"202":{"description":"The turn was stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterruptAgentSessionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Session not found, or not created by the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`NOT_ACTIVE`: nothing was stopped, because the turn had already\nended (or `expectedTurn` isn't the current turn). `status` and\n`turn` are the session's.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionNotActive"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://guide.plusai.com/apis-for-presentations/api-reference/presentation-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
