Documentation

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 return forbidden_scope.
  • Endpoint allowlist: restrict a key to specific endpoints within its scopes. MCP tools/list only 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-cache header or meta.cache: hit, stale, miss or bypass.
  • Pass max_age (seconds) to bound how old a result may be. max_age: 0 or Cache-Control: no-cache forces a fresh fetch.
  • age reports how old the served result is, in seconds.

Errors

Errors return { success: false, error: { code, message }, meta: { request_id } }.

invalid_request400Input failed validation, or the request was malformed. `error.details` lists each field.
unauthorized401Missing API key, or no signed-in session for dashboard routes.
invalid_api_key401Malformed, unknown or revoked key.
api_key_revoked401The key was revoked. Create or roll a new one.
api_key_expired401The key passed its expiry date.
forbidden_scope403The key lacks the scope this endpoint needs, or the endpoint is outside its endpoint allowlist.
forbidden_ip403The request came from an IP outside the key's IP allowlist.
forbidden403The signed-in user is not allowed to perform this action.
account_suspended403The account is suspended. Every key is disabled until support restores it.
email_unverified403Confirm your email address before creating keys or using the playground.
not_found404Unknown route, endpoint or resource.
not_cached404A cache-only lookup found no stored result.
content_too_large413The request body exceeds the size limit (64 KB).
blocked_target422The URL points at a private, internal or disallowed host.
rate_limited429Too many requests this minute for this key. Honor `Retry-After`.
quota_exceeded429Monthly credits used, either the account allowance or the key's own cap. Cached responses still work.
internal_error500Something failed on our side. Include `meta.request_id` when contacting support.
upstream_error502The target site or a provider failed. Failures are cached for 60s.
billing_unavailable503Billing is not configured or the payment provider is unreachable.
upstream_timeout504The 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.

Fetch

1 creditscope: webcache 1h + swr 1d

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.

ParameterTypeDescription
url *stringAbsolute http(s) URL. A bare domain is accepted and upgraded to https.
formatmarkdown | html | text
= "markdown"
Output format of `content`.
engineauto | 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_contentboolean
= true
Strip navigation, ads and boilerplate.
include_linksboolean
= false
Return outbound links found in the content.
max_ageintegerOldest 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

2 creditsscope: webcache 15m + swr 1h

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.

ParameterTypeDescription
q *stringSearch query.
limitinteger
= 8
Number of results.
sitestringRestrict results to one domain, e.g. docs.python.org.
include_contentboolean
= false
Also read the top 3 results and return their content as Markdown (+1 credit each).
max_ageintegerOldest 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

Design.md

3 creditsscope: brandcache 7d + swr 30d

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.

ParameterTypeDescription
url *stringAbsolute http(s) URL. A bare domain is accepted and upgraded to https.
max_ageintegerOldest 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

Brand

5 creditsscope: brandcache 7d + swr 30d

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.

ParameterTypeDescription
domain *stringDomain (stripe.com) or any URL on it.
include_design_mdboolean
= true
Include the generated DESIGN.md for the site.
max_ageintegerOldest 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

Map

2 creditsscope: webcache 1d + swr 7d

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.

ParameterTypeDescription
url *stringDomain (stripe.com) or any URL on it.
limitinteger
= 200
Maximum URLs to return.
searchstringOnly return URLs containing this text.
include_subdomainsboolean
= false
max_ageintegerOldest 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

Weather

1 creditscope: utilitycache 10m + swr 30m

GET | POST /v1/weather

Geocodes a place name and returns current weather plus up to a 16-day forecast.

ParameterTypeDescription
qstringPlace name, e.g. `Berlin` or `Austin, TX`.
latnumber
lonnumber
daysinteger
= 3
Forecast days.
unitsmetric | imperial
= "metric"
max_ageintegerOldest 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

Exchange rates

1 creditscope: utilitycache 1h + swr 6h

GET | POST /v1/fx

Daily reference exchange rates published by the European Central Bank, with amount conversion.

ParameterTypeDescription
basestring
= "USD"
ISO 4217 base currency.
symbolsstringComma-separated target currencies, e.g. `EUR,GBP,INR`. Omit for all.
amountnumber
= 1
datestringHistorical date (YYYY-MM-DD). Omit for latest.
max_ageintegerOldest 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)

DNS

1 creditscope: utilitycache 5m + swr 5m

GET | POST /v1/dns

Resolves records through Cloudflare's 1.1.1.1 resolver. Results are cached for the record's own TTL.

ParameterTypeDescription
name *stringHostname to resolve.
typeA | 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_ageintegerOldest 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

WHOIS

1 creditscope: utilitycache 1d + swr 7d

GET | POST /v1/whois

Registrar, dates, status and nameservers for a domain, or network owner for an IP, via RDAP.

ParameterTypeDescription
query *stringDomain name or IP address.
max_ageintegerOldest 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

Wikipedia

1 creditscope: utilitycache 1d + swr 7d

GET | POST /v1/wiki

Finds the best-matching Wikipedia article and returns its summary, thumbnail and Wikidata ID.

ParameterTypeDescription
q *stringTopic, person, company or place.
langstring
= "en"
max_ageintegerOldest 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

Public holidays

1 creditscope: utilitycache 30d + swr 30d

GET | POST /v1/holidays

National and regional public holidays for a country and year.

ParameterTypeDescription
country *stringISO 3166-1 alpha-2 country code.
yearintegerDefaults to the current year.
max_ageintegerOldest 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

Stock quote

1 creditscope: utilitycache 1m + swr 5m

GET | POST /v1/stock

Current price, daily change and range for a listed company, plus its exchange, industry, market cap, website and logo.

ParameterTypeDescription
symbol *stringTicker such as AAPL or NVDA. A company name also works and resolves to its primary listing.
max_ageintegerOldest 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