# Source: https://docs.pipecat.ai/deployment/pipecat-cloud/guides/session-api.md

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

# Session API

> 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  theme={null}
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  theme={null}
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  theme={null}
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  theme={null}
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  theme={null}
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  theme={null}
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  theme={null}
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).