Skip to content

KeyPool Integration Guide

KeyPool gives your team one stable API surface for AI services that each have their own auth headers, quotas, and SDK quirks.

What You Get

  • One team token for every supported service.
  • Shared service access through one stable endpoint per supported provider.
  • Consistent failure handling when a provider is temporarily unavailable or rate-limited.
  • Usage controls defined by your KeyPool workspace.
  • Service-specific guidance for SDK setup, base URLs, and edge cases.

Start Here

  1. Get your KeyPool Team Token from your workspace admin.
  2. Pick the service you want to integrate from the navigation.
  3. Set KEYPOOL_BASE_URL to the base URL provided by your KeyPool administrator.
  4. Send Authorization: Bearer <TEAM_TOKEN> on every request to KeyPool.
  5. Use the API Reference page to test the exact service endpoints in-browser.

Base URL Patterns

Most services use the same URL pattern:

https://your-keypool.example.com/v1/{service}

Two services use a service header for SDK compatibility:

  1. Firecrawl SDKs should target the KeyPool origin and use x-keypool-service: firecrawl.
  2. Tavily examples in this guide use the KeyPool origin plus x-keypool-service: tavily for the same reason.

Availability And Errors

KeyPool may retry a request internally when a provider returns a retryable per-key error and the request body can be replayed. If no usable provider credential is available for a service, KeyPool returns a JSON error with HTTP 503. If your team token is rate-limited, KeyPool returns HTTP 429.

For production integrations, treat 429, 502, and 503 as retryable with backoff unless the service-specific guide says otherwise. Contact your workspace admin if one service consistently returns 503; admins can check the pool monitor and credential eligibility without changing client code.

Supported Services