ActionLayer API
Every endpoint accepts GET with query parameters or POST with a JSON body, and returns { success, data, meta }. Machine-readable specs: OpenAPI and llms.txt.
Quickstart
Create a key in the dashboard, export it, then call any endpoint.
curl https://actionlayer.fiftyseven.is/v1/fetch \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://blog.cloudflare.com"}'Authentication
Send your key as Authorization: Bearer al_live_... (or x-api-key). Keys in query strings are rejected, since URLs end up in logs. Keys carry scopes (web, brand, utility), can expire, and can be rolled or revoked from the dashboard. Keys are 46 characters with a built-in checksum, so secret scanners can detect them.
Key controls
Each key can be narrowed from its page in the dashboard. Changes apply within about 30 seconds everywhere.
- Scopes:
web(fetch, search, map);brand(design, brand);utility(weather, fx, dns, whois, wiki, holidays, stock). Calls outside them returnforbidden_scope. - Endpoint allowlist: restrict a key to specific endpoints within its scopes. MCP
tools/listonly shows the tools a key may call. - IP allowlist: exact IPv4/IPv6 addresses or CIDR ranges. Other clients get
forbidden_ip. - Per-key rate limit: requests per minute below your plan limit, so one agent cannot starve the others.
- Per-key monthly cap: a credit ceiling for that key. When reached, uncached calls on it return
quota_exceeded; other keys keep working. - Account cap and alerts: in Settings, set a monthly credit cap below your plan allowance and an email alert threshold (default 80%). A second email is sent at 100%.
Credits are reserved atomically before any upstream work, so parallel requests can never overrun a cap. If the call fails, or an identical request finishes first and the result is shared, the reservation is refunded. Cache hits never touch your quota.
Caching
Results are cached in three tiers: identical in-flight requests are coalesced, then a per-location edge cache, then global KV for expensive endpoints. Stale entries are served instantly while refreshing in the background. Inputs are canonicalized, so https://Stripe.com/?utm_source=x and stripe.com share an entry.
- Cache hits cost 0 credits. Check the
x-cacheheader ormeta.cache:hit,stale,missorbypass. - Pass
max_age(seconds) to bound how old a result may be.max_age: 0orCache-Control: no-cacheforces a fresh fetch. agereports how old the served result is, in seconds.
Errors
Errors return { success: false, error: { code, message }, meta: { request_id } }.
| invalid_request | 400 | Input failed validation, or the request was malformed. `error.details` lists each field. |
| unauthorized | 401 | Missing API key, or no signed-in session for dashboard routes. |
| invalid_api_key | 401 | Malformed, unknown or revoked key. |
| api_key_revoked | 401 | The key was revoked. Create or roll a new one. |
| api_key_expired | 401 | The key passed its expiry date. |
| forbidden_scope | 403 | The key lacks the scope this endpoint needs, or the endpoint is outside its endpoint allowlist. |
| forbidden_ip | 403 | The request came from an IP outside the key's IP allowlist. |
| forbidden | 403 | The signed-in user is not allowed to perform this action. |
| account_suspended | 403 | The account is suspended. Every key is disabled until support restores it. |
| email_unverified | 403 | Confirm your email address before creating keys or using the playground. |
| not_found | 404 | Unknown route, endpoint or resource. |
| not_cached | 404 | A cache-only lookup found no stored result. |
| content_too_large | 413 | The request body exceeds the size limit (64 KB). |
| blocked_target | 422 | The URL points at a private, internal or disallowed host. |
| rate_limited | 429 | Too many requests this minute for this key. Honor `Retry-After`. |
| quota_exceeded | 429 | Monthly credits used, either the account allowance or the key's own cap. Cached responses still work. |
| internal_error | 500 | Something failed on our side. Include `meta.request_id` when contacting support. |
| upstream_error | 502 | The target site or a provider failed. Failures are cached for 60s. |
| billing_unavailable | 503 | Billing is not configured or the payment provider is unreachable. |
| upstream_timeout | 504 | The target did not respond in time. |
Rate limits and quota
Limits apply per key per minute: Free 60/min, Pro 600/min. Responses include ratelimit-limit and, where available, ratelimit-remaining and ratelimit-reset. Monthly credits: Free 1,000, Pro 100,000.
MCP server
ActionLayer is a remote MCP server (Streamable HTTP) at https://actionlayer.fiftyseven.is/mcp. Every endpoint is a tool with the same input schema. Authenticate with the same bearer key.
{
"mcpServers": {
"actionlayer": {
"url": "https://actionlayer.fiftyseven.is/mcp",
"headers": { "Authorization": "Bearer ${ACTIONLAYER_API_KEY}" }
}
}
}json-render UI
Add ?ui=true to any request and the response includes a json-render spec in ui. It uses shadcn components plus Swatch, Code, Stat and KeyValue, so generative-UI apps can show results without writing components.
GET | POST /v1/fetch
Fetches a page at the edge, extracts the main content and converts it to LLM-ready Markdown. Falls back to Jina Reader for JavaScript-rendered or blocked pages.
| Parameter | Type | Description |
|---|---|---|
| url * | string | Absolute http(s) URL. A bare domain is accepted and upgraded to https. |
| format | markdown | html | text = "markdown" | Output format of `content`. |
| engine | auto | native | jina = "auto" | `native` fetches and parses at the edge. `jina` renders through Jina Reader (handles JS-heavy pages). `auto` tries native and falls back to Jina when the page is blocked, empty or client-rendered. |
| main_content | boolean = true | Strip navigation, ads and boilerplate. |
| include_links | boolean = false | Return outbound links found in the content. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/fetch \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://blog.cloudflare.com"}'Upstreams: Edge fetch, Jina Reader
GET | POST /v1/search
Searches the live web and returns ranked results with snippets. Set `include_content` to read the top results in the same call.
| Parameter | Type | Description |
|---|---|---|
| q * | string | Search query. |
| limit | integer = 8 | Number of results. |
| site | string | Restrict results to one domain, e.g. docs.python.org. |
| include_content | boolean = false | Also read the top 3 results and return their content as Markdown (+1 credit each). |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/search \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"durable objects vs d1 consistency","limit":5}'Upstreams: LangSearch, Jina Search, Autom (Google), Exa via Composio, Brave Search, DuckDuckGo
GET | POST /v1/design
Reads a page and its stylesheets, then returns the design tokens (colors, type, radii, shadows, spacing) and a DESIGN.md an agent can follow to build on-brand UI.
| Parameter | Type | Description |
|---|---|---|
| url * | string | Absolute http(s) URL. A bare domain is accepted and upgraded to https. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/design \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://linear.app"}'Upstreams: Edge fetch
GET | POST /v1/brand
Resolves a domain to a brand profile: name, description, logo candidates, palette, typography, social profiles and company facts from Wikidata, plus the site's DESIGN.md.
| Parameter | Type | Description |
|---|---|---|
| domain * | string | Domain (stripe.com) or any URL on it. |
| include_design_md | boolean = true | Include the generated DESIGN.md for the site. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/brand \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"stripe.com"}'Upstreams: Edge fetch, Wikidata, Google favicons
GET | POST /v1/map
Reads robots.txt and sitemaps (including sitemap indexes) to list a site's URLs, falling back to on-page links when no sitemap exists.
| Parameter | Type | Description |
|---|---|---|
| url * | string | Domain (stripe.com) or any URL on it. |
| limit | integer = 200 | Maximum URLs to return. |
| search | string | Only return URLs containing this text. |
| include_subdomains | boolean = false | |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/map \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"vercel.com","limit":50,"search":"blog"}'Upstreams: Edge fetch
GET | POST /v1/weather
Geocodes a place name and returns current weather plus up to a 16-day forecast.
| Parameter | Type | Description |
|---|---|---|
| q | string | Place name, e.g. `Berlin` or `Austin, TX`. |
| lat | number | |
| lon | number | |
| days | integer = 3 | Forecast days. |
| units | metric | imperial = "metric" | |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/weather \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"Bengaluru","days":3}'Upstreams: Open-Meteo
GET | POST /v1/fx
Daily reference exchange rates published by the European Central Bank, with amount conversion.
| Parameter | Type | Description |
|---|---|---|
| base | string = "USD" | ISO 4217 base currency. |
| symbols | string | Comma-separated target currencies, e.g. `EUR,GBP,INR`. Omit for all. |
| amount | number = 1 | |
| date | string | Historical date (YYYY-MM-DD). Omit for latest. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/fx \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"base":"USD","symbols":"EUR,INR,JPY","amount":250}'Upstreams: Frankfurter (ECB)
GET | POST /v1/dns
Resolves records through Cloudflare's 1.1.1.1 resolver. Results are cached for the record's own TTL.
| Parameter | Type | Description |
|---|---|---|
| name * | string | Hostname to resolve. |
| type | A | AAAA | CNAME | MX | TXT | NS | SOA | CAA | SRV | HTTPS | ALL = "A" | Record type. `ALL` resolves A, AAAA, CNAME, MX, TXT, NS and CAA in parallel. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/dns \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"github.com","type":"ALL"}'Upstreams: Cloudflare 1.1.1.1
GET | POST /v1/whois
Registrar, dates, status and nameservers for a domain, or network owner for an IP, via RDAP.
| Parameter | Type | Description |
|---|---|---|
| query * | string | Domain name or IP address. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/whois \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"openai.com"}'Upstreams: RDAP
GET | POST /v1/wiki
Finds the best-matching Wikipedia article and returns its summary, thumbnail and Wikidata ID.
| Parameter | Type | Description |
|---|---|---|
| q * | string | Topic, person, company or place. |
| lang | string = "en" | |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/wiki \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"Cloudflare"}'Upstreams: Wikipedia
GET | POST /v1/holidays
National and regional public holidays for a country and year.
| Parameter | Type | Description |
|---|---|---|
| country * | string | ISO 3166-1 alpha-2 country code. |
| year | integer | Defaults to the current year. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/holidays \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"country":"US"}'Upstreams: Nager.Date
GET | POST /v1/stock
Current price, daily change and range for a listed company, plus its exchange, industry, market cap, website and logo.
| Parameter | Type | Description |
|---|---|---|
| symbol * | string | Ticker such as AAPL or NVDA. A company name also works and resolves to its primary listing. |
| max_age | integer | Oldest cached result you will accept, in seconds. 0 forces a fresh fetch. Omit to use the endpoint default. |
curl https://actionlayer.fiftyseven.is/v1/stock \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"symbol":"NVDA"}'Upstreams: Finnhub via Composio