Add Session API documentation

deployment/pipecat-cloud/guides/session-api.mdx

@@ -0,0 +1,149 @@
+---
+title: Session API
+description: "Send HTTP requests to your running Pipecat Cloud sessions"
+---
+
+The Session API lets you send HTTP requests directly to your running Pipecat Cloud agents. This enables real-time control and data exchange with active sessions, such as updating conversation context, triggering actions, or retrieving session state.
+
+## How It Works
+
+1. [Start a session](/deployment/pipecat-cloud/fundamentals/active-sessions) with your agent
+2. Capture the `sessionId` header from the start response
+3. Send HTTP requests to your session using the session endpoint
+
+## Endpoint Format
+
+```
+https://api.pipecat.daily.co/v1/public/{service_name}/sessions/{session_id}/{path}
+```
+
+| Parameter      | Description                                   |
+| -------------- | --------------------------------------------- |
+| `service_name` | The name of your deployed agent               |
+| `session_id`   | The `sessionId` value from the start response |
+| `path`         | The endpoint path you defined in your bot     |
+
+### Supported Methods
+
+- `GET`
+- `POST`
+- `PUT`
+- `PATCH`
+- `DELETE`
+- `OPTIONS`
+- `HEAD`
+
+## Authentication
+
+Include your Pipecat Cloud public API key in the `Authorization` header:
+
+```bash
+Authorization: Bearer pk_...
+```
+
+## Setting Up Your Bot
+
+To handle Session API requests, define endpoints in your `bot.py` file using the `app` object from `pipecatcloud_system`:
+
+```python
+from pipecatcloud_system import app
+from pipecat.runner.types import PipecatRunnerArguments
+
+# Define your API endpoints
+@app.get("/status")
+async def get_status():
+    return {"status": "active", "message": "Bot is running"}
+
+@app.post("/update-context")
+async def update_context(data: dict):
+    # Handle context updates
+    return {"updated": True}
+
+# Your main bot function
+async def bot(args: PipecatRunnerArguments):
+    # Bot implementation
+    pass
+```
+
+<Note>Requires base image version `0.1.2` or later.</Note>
+
+## Examples
+
+### Get Session Status
+
+Define an endpoint that returns the current session state:
+
+```python
+from pipecatcloud_system import app
+
+session_data = {"messages": [], "user_name": None}
+
+@app.get("/status")
+async def get_status():
+    return {
+        "message_count": len(session_data["messages"]),
+        "user_name": session_data["user_name"]
+    }
+```
+
+Call the endpoint:
+
+```bash
+curl -X GET \
+  'https://api.pipecat.daily.co/v1/public/my-agent/sessions/57af5437-97a2-4646-9873-a5c5935bd705/status' \
+  -H 'Authorization: Bearer pk_...'
+```
+
+### Update Conversation Context
+
+Define an endpoint to inject information into the conversation:
+
+```python
+from pipecatcloud_system import app
+from pydantic import BaseModel
+
+class ContextUpdate(BaseModel):
+    user_name: str
+    preferences: dict
+
+@app.post("/context")
+async def update_context(update: ContextUpdate):
+    # Update your bot's context with the new information
+    # This could modify the LLM system prompt, add to conversation history, etc.
+    return {"status": "context updated", "user_name": update.user_name}
+```
+
+Call the endpoint:
+
+```bash
+curl -X POST \
+  'https://api.pipecat.daily.co/v1/public/my-agent/sessions/57af5437-97a2-4646-9873-a5c5935bd705/context' \
+  -H 'Authorization: Bearer pk_...' \
+  -H 'Content-Type: application/json' \
+  -d '{"user_name": "Alice", "preferences": {"language": "Spanish"}}'
+```
+
+### Trigger an Action
+
+Define an endpoint to trigger bot behavior mid-session:
+
+```python
+from pipecatcloud_system import app
+
+@app.post("/speak")
+async def trigger_speech(data: dict):
+    message = data.get("message", "Hello!")
+    # Queue the message for your TTS pipeline
+    # Implementation depends on your bot architecture
+    return {"queued": True, "message": message}
+```
+
+## Important Notes
+
+- **Startup latency**: If you call the Session API before your bot finishes initializing, the request may take longer while waiting for the bot to become available.
+- **Session scope**: Each endpoint call is routed to the specific session identified by `session_id`. Different sessions run independently.
+- **Error handling**: If a session has ended or the session ID is invalid, you'll receive an error response.
+
+## Getting Help
+
+If you have questions about the Session API, reach out on [Discord](https://discord.gg/pipecat).

deployment/pipecat-cloud/rest-reference/endpoint/session-proxy.mdx

@@ -0,0 +1,21 @@
+---
+title: "Session API"
+description: "Send HTTP requests directly to your running Pipecat Cloud agent sessions."
+openapi: "GET /{serviceName}/sessions/{sessionId}/{path}"
+---
+
+Send HTTP requests to endpoints defined in your running bot. Supports `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, and `HEAD` methods.
+
+## Request Headers
+
+Headers are forwarded to your bot with these exceptions:
+
+- `host` - Excluded
+- `content-length` - Excluded
+- `authorization` - Excluded (authentication is handled by the API gateway)
+
+<Note>
+  Requires base image version `0.1.2` or later. See the [Session API
+  guide](/deployment/pipecat-cloud/guides/session-api) for setup instructions
+  and examples.
+</Note>