Skip to main content
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 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}
ParameterDescription
service_nameThe name of your deployed agent
session_idThe sessionId value from the start response
pathThe 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: 
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: 
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
Requires base image version 0.1.2 or later.

​
Examples

​
Get Session Status

Define an endpoint that returns the current session state: 
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: 
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: 
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: 
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: 
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.