> ## 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.

# Quickstart

> Get an API key and make your first request

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`.

```bash theme={null}
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

* Sign in at [https://app.shoal.xyz](https://app.shoal.xyz)
* Create an API key and copy it somewhere secure

## 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.

```bash theme={null}
curl -fsSL https://api.shoal.xyz/install | bash
```

Then authenticate and start querying:

```bash theme={null}
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:

```text theme={null}
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](/integrations/mcp)

***

## Make Your First Request

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

## Test Request (Python)

```python theme={null}
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)

```javascript theme={null}
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

```bash theme={null}
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