Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Networking

  • Set reasonable timeouts (e.g., 10–30s) and retry on transient failures
  • Use HTTPS only; verify certificates by default

​
Authentication

  • Store API keys securely (env vars, secret stores)
  • Do not embed keys in client-side code or public repos

​
Pagination & Memory

  • Prefer paginated fetches over large single responses
  • Stream or process items incrementally where possible
  • Prefer scoped routes (entities/byId, timeline/byOrganizationId, signal/top) over bulk /all routes unless you genuinely need premium feed behavior

​
Route Selection

  • Start with /v1/search for most prototypes and first integrations
  • Resolve stable Shoal entity ids with /v1/entities/byName before building recurring monitoring workflows
  • Treat /all endpoints as premium bulk-feed surfaces, not as the default polling path
  • Use /v1/usage and response headers to understand the route class and budget impact of each request
  • Treat /v1/organizations/* as compatibility routes, not the primary integration path for new builds

​
Observability

  • Log request IDs and timestamps alongside responses
  • Log X-Api-Surface, X-Access-Layer, and X-Endpoint-Policy if you are building a multi-endpoint integration
  • Add a descriptive User-Agent (e.g., your-app/1.2.3)