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.

Base URL: https://api.shoal.xyz/v1

​
Fastest Path

For launch, the default Shoal flow should be entity-first:
  1. resolve a canonical entity by name
  2. inspect its recent timeline or relationships
  3. use search when you need broader discovery beyond one entity
Start with /v1/entities/byName. 
curl -sS "https://api.shoal.xyz/v1/entities/byName?name=ethereum&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
Then use the returned Shoal id to traverse the semantic layer.

​
Get an API Key

​
Access Model

Shoal routes are packaged into three access layers:
  • evaluation — lookup, scoped feeds, search, and usage introspection
  • operational — higher-value workflow surfaces like briefs
  • premium — bulk feeds, directory-style export surfaces, and delivery primitives like webhooks
The API now exposes this model in response headers:
  • X-Api-Surface
  • X-Access-Layer
  • X-Endpoint-Policy
Example:
  • /v1/entities/byName -> registry surface, evaluation layer
  • /v1/search -> query surface, evaluation layer
  • /v1/radar/all -> feed surface, premium layer
That means the right integration strategy is usually:
  1. resolve an entity by name
  2. inspect entity detail, relationships, or timeline
  3. use search for broader discovery
  4. use feed, webhook, and export surfaces only when the workflow justifies them

​
Install the CLI (Optional)

The fastest way to explore the API — no code required. 
curl -fsSL https://api.shoal.xyz/install | bash
Then authenticate and start querying: 
shoal auth YOUR_API_KEY
shoal entity search ethereum
shoal entity relationships 23151
shoal timeline entity 23151 --since 7d

​
Connect an AI Agent (Optional)

If you want Shoal available as native tools inside an MCP-compatible agent, use the hosted MCP server: 
https://api.shoal.xyz/mcp
Authentication happens through app.shoal.xyz. The account must already have a valid API key with remaining quota. Full setup: MCP Server

​
Make Your First Request

curl -sS "https://api.shoal.xyz/v1/entities/byName?name=ethereum&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Test Request (Python)

import os, requests

API_KEY = os.environ.get("SHOAL_API_KEY", "YOUR_API_KEY")
resp = requests.get(
    "https://api.shoal.xyz/v1/entities/byName",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"name": "ethereum", "limit": 5},
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

​
Test Request (JavaScript)

const API_KEY = process.env.SHOAL_API_KEY || 'YOUR_API_KEY';
const url = new URL('https://api.shoal.xyz/v1/entities/byName');
url.searchParams.set('name', 'ethereum');
url.searchParams.set('limit', '5');

const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);

​
Resolve an Entity When Needed

curl -sS "https://api.shoal.xyz/v1/entities/byName?name=ethereum" \
  -H "Authorization: Bearer YOUR_API_KEY"
Use entity lookup when you want the stable Shoal id for repeated monitoring and traversal. The older organizations/byOrganizationName route remains available as a compatibility surface.

​
Core Event Shape

Radar, Signal, Search, Brief, and webhook payloads are converging on one shared event object. Build new integrations against these canonical fields:
  • summary
  • bullets
  • owners
  • participants
  • evidence
  • latestEvidenceTimestamp
  • significance
Older compatibility fields like globalSummary, bulletSummary, eventOwner, eventParticipants, posts, latestPostTimestamp, and signal may still appear during the transition.

​
Next Steps

  • Resolve an entity name: /v1/entities/byName?name=ethereum
  • Fetch one entity: /v1/entities/byId?id=<entity_id>
  • Traverse relationships: /v1/entities/<entity_id>/relationships
  • Query one entity timeline: /v1/timeline/byOrganizationId?id=<entity_id>&since=<iso_timestamp>
  • Search broader context: /v1/search?query=ethereum%20foundation
  • Inspect current budget and plan headers: /v1/usage

​
Common Errors

  • 400 Bad Request: missing required parameter (e.g., since, id, category) or invalid timestamp
  • 401 Unauthorized: missing or malformed Authorization header
  • 403 Forbidden: invalid API key or endpoint not available on the current plan
  • 404 Not Found: invalid endpoint path
  • 429 Too Many Requests: rate limit exceeded (100 req/min per key)
  • 500 Internal Server Error: temporary issue; retry with backoff