Session Management Best Practices

This guide covers best practices for managing PizzaStack sessions effectively.

Session Lifecycle

Creating a Session

Sessions are created automatically on your first request with a given X-Session-ID. Use a UUID for each new workflow.

import requests
import uuid

API_BASE = "https://api.tomatopy.pizza/v1"

def create_session_headers(api_key):
    """Create headers for a new session."""
    return {
        "Content-Type": "application/json",
        "X-API-Key": api_key,
        "X-Session-ID": str(uuid.uuid4())
    }

headers = create_session_headers("your-api-key")

One Session Per Workflow

Each independent pizza-making workflow should use its own session. Do not reuse a session ID for unrelated workflows.

Session Expiration

Sessions expire after a period of inactivity. Plan your workflows to complete within a reasonable timeframe.

Checking Session State

Using the Debug Endpoint

The GET /v1/session/{session_id}/log endpoint shows all objects and operations in a session. Use it to debug issues.

Debugging Quality Issues

If your final pizza has a low quality score, use the session log to trace the problem:

Managing Multiple Concurrent Workflows

When running multiple workflows in parallel, each should have its own session:

Best Practices Summary

  1. One session per workflow -- never mix unrelated operations in a single session

  2. Use UUIDs for session IDs -- avoids collisions

  3. Check session state when debugging -- the log endpoint shows all objects and their quality

  4. Handle session expiration -- create a new session if the old one has expired

  5. Keep sessions short-lived -- complete your workflow promptly rather than leaving sessions open

Next Steps

Last updated

Was this helpful?