Cookbooks

Cookbooks are guided multi-step workflows that combine multiple APIs. Think of them as recipes for agents.

Concepts

Cookbook

A template that defines a workflow — e.g. "Daily Weather Briefing" or "Lead Enrichment Pipeline".

Each cookbook has:

• Steps — Ordered actions to complete the workflow
• API Slots — Which API roles are needed (e.g. "weather_provider", "email_sender")
• Alternatives — Swappable APIs for each slot

Session

When an agent starts a cookbook, it creates a session — a stateful instance tracking progress.

Steps

Each step is either:

• Agent step — The agent calls an API via the proxy
• Human step — Requires manual action (e.g. "verify the output")

Workflow

1. Browse Cookbooks

GET /api/v1/cookbooks

Returns all available cookbooks with metadata.

2. Get Cookbook Details

GET /api/v1/cookbooks/{id}

Returns full cookbook with steps, API slots, and alternatives. Costs $0.005.

3. Start a Session

POST /api/v1/cookbooks/{id}/start
Body: { "selectedApis": { "weather_provider": "openweathermap" } }

Creates a session with your API choices for each slot.

4. Get Current Step

GET /api/v1/cookbooks/sessions/{sessionId}/step

Returns the current step with instructions and API-specific guidance.

5. Complete Step

POST /api/v1/cookbooks/sessions/{sessionId}/complete-step
Body: { "stepId": "step-1", "resultData": { ... } }

Marks the step complete and advances to the next one.

6. Check Status

GET /api/v1/cookbooks/sessions/{sessionId}

Returns session status, current step, and completion progress.

API Slots & Alternatives

Cookbooks define slots — abstract roles like "search_engine" or "email_provider".

Each slot has a default API and alternatives:

{
  "slot": "weather_provider",
  "slotLabel": "Weather Data",
  "defaultApiId": "openweathermap",
  "alternatives": [
    { "apiId": "weatherapi", "reason": "More detailed forecasts" },
    { "apiId": "visualcrossing", "reason": "Historical data included" }
  ]
}

Agents can pick any alternative when starting a session.