Sugra API

View saved version →

---
name: auth-and-quota
description: Use a Sugra key, stay inside the daily quota, and act on each error over HTTPS or MCP. Use when the user needs a key, before a bulk call, or when a call returns 400, 401, 404, 422, 429, 5xx, missing_api_key, missing_bearer_token, unknown_parameters, needs_params, or upstream_*.
license: MIT
---

# Auth and quota

One key. Volume gating only: every plan sees every endpoint. Plans and errors on https://docs.sugra.ai (search Authentication, Rate limits).

Sign up at https://app.sugra.ai/register: a Free key is issued at signup. Keys: https://app.sugra.ai/developer/keys. Plans and prices: https://sugra.systems/api/pricing. Prefix `sugra_...`. Do not log the key, and do not put it in a skill file, a commit, or a chat.

Free: 50 requests a day. Paid plans raise that volume; the volume and price of each plan are on the pricing page.

The daily quota belongs to the account, not to one key: every key of the account draws on the same count. It resets at 00:00 UTC.

A keyed data call costs at least 1 request. The public system endpoints (`/health`, `/sources`, `/openapi.json`) and the stdio catalog tools make no data call. Before a bulk call read MCP `describe_endpoint` `agent_hints.bulk_cost`. Over HTTPS, `X-RateLimit-Remaining` on each keyed response shows what is left. Over MCP, hosted composed tools report their own cost in `billing` (`rate_limit_cost`, `downstream_calls`, `remaining`), and one composed call can spend more than 1 request.

## HTTPS API

```
x-api-key: sugra_...
```

On `https://sugra.ai` the key goes only in the `x-api-key` header.

Keyed responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (the last second of the UTC quota day in ISO 8601, `YYYY-MM-DDT23:59:59Z`), and `X-Request-ID`. A 429 also carries `Retry-After` (seconds).

## MCP

How each MCP client signs in to the Sugra API MCP server: https://docs.sugra.ai/doc-2263382.

MCP tool JSON does not forward `X-RateLimit-*`. Read an MCP error's `error` first, then follow its `hint` or `retry_hint` when it has one. When the API answered, the error has a numeric `status_code`, plus `request_id` (the API's `X-Request-ID`) and `retry_after` (seconds) when the API sent them. A network failure (`upstream_timeout`, `upstream_connect_error`, `upstream_transport_error`) has no HTTP status and carries a `reason`. An answer too large for MCP comes back trimmed with `meta.truncated`, or as `response_too_large`: narrow the filters. Catalog and validation errors (`unknown_parameters`, `missing_required_parameters`, `needs_params`, `missing_required_parameter_groups`, `unknown_operation_id`) make no API call and carry their own fields (table below).

## Errors

Read the message before anything else: it usually names the fix.

| Signal | Meaning | What to do |
|---|---|---|
| HTTP 400 / 422 | a parameter is missing, malformed, or out of range | find which one in the message (over MCP a 422 can arrive as a bare `HTTP 422`: then check every parameter against `describe_endpoint`), fix it, then call again |
| MCP `unknown_parameters` (hosted server only) | a key the operation does not declare | use a name from `accepted` or `did_you_mean` |
| MCP `missing_required_parameters` / `needs_params` / `missing_required_parameter_groups` | required parameters are missing | fill them from the returned list, then call again |
| MCP `unknown_operation_id` | the id is not in the catalog | search again; do not guess an id |
| HTTP 404 | no such path, or no such item (an airport, a paper, a series) | if the message names a missing item, fix the input; otherwise check the path on docs.sugra.ai. Do not guess |
| HTTP 401 / MCP `missing_api_key` / `missing_bearer_token` | missing or invalid credential | stop. Do not retry the same call. Over MCP, point the user to the sign-in page in MCP above |
| HTTP 429 / MCP 429 | the account's quota is spent, or a short protective limit | wait for `Retry-After` / `retry_after`, or until `X-RateLimit-Reset`. On the hosted server a spent quota carries `reason: daily_limit_reached` (with `daily_limit` and `plan` when known): tell the user it resets at 00:00 UTC |
| MCP `server_busy` / `deadline_exceeded` | the MCP server is at its limit, or the call ran past its time budget | do what its `retry_hint` says |
| HTTP 5xx / MCP `upstream_*` | platform or upstream fault | if the message says the input does not exist (an unknown series or identifier), fix the input; otherwise retry once with backoff, then tell the user to write to support@sugra.systems with `X-Request-ID` / `request_id` when there is one, else with the whole error |

Do not retry a 4xx unchanged. Retry a 429 only after the wait it names.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: cross-domain-briefing
description: Compose one briefing from two or three Sugra directions over HTTPS or MCP. Use when a question spans Finance, Macro, Entity, Net Atlas, News, Earth, or Research and one operation is not enough.
license: MIT
---

# Cross-domain briefing

Split the question. Call two or three operations. Do not invent a combined index. HTTP and MCP are both valid; use the surface already connected. Confirm each operation on https://docs.sugra.ai.

## Pattern

1. Split the question into 2-3 concrete asks (place, series, snapshot). Name the directions involved (Finance, Macro, Entity, Net Atlas, News, Earth, Research).
2. For each ask, discover then call (`discover-and-call`). Prefer sovereign or intergovernmental sources when the catalog offers them.
3. Keep units, geography, and clocks separate. Do not blend a port throughput z-score with a weather reading into one invented number.
4. Quote each figure with its source from `meta` (or `_meta` on a flat payload) and its date: an `as_of` when present (in a record, in `data`, or in `meta`), `meta.period`, or a `data_time` the source stated, never one that fell back to the response time. With none of them, say the source time is unavailable (see `envelope-and-attribution`).
5. Close with what the catalog did not cover, not a prediction.

## Example shape (not a canned path list)

"What is happening around a chokepoint this week?" can be three calls: port throughput (Sugra Earth / transport), conditions at a coordinate on the route (Sugra Earth), and one related sovereign or intergovernmental series docs.sugra.ai actually lists. Discover, call, present side by side.

The MCP prompt `earth_conditions` is a one-coordinate recipe for weather, air quality, and nearby hazards. This skill is the longer form when those conditions are only one pane.

Do not add per-endpoint MCP tools. Do not treat screening as a briefing source unless the question is about a named party. On MCP, stay on the gateway tools so the briefing works on stdio and hosted alike. Do not frame the output as investment, legal, or routing advice.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: discover-and-call
description: Find the right Sugra operation, call it over HTTPS or MCP, and check that the result answers the question. Use when the path or operation_id is unknown, before guessing parameters, before quoting a figure, or after a catalog miss. Confirm details on https://docs.sugra.ai. Do not invent routes.
license: MIT
---

# Discover and call

Do not invent paths or `operation_id`s. Confirm the operation on https://docs.sugra.ai (search or Ask AI, then the endpoint page). Two complete loops, same API.

## HTTP loop

1. If the path is already known, skip to step 4 after confirming it on docs.sugra.ai.
2. Search https://docs.sugra.ai. Machine companion: `GET https://sugra.ai/openapi.json`. List of source names: `GET https://sugra.ai/sources`.
3. Read every parameter with its default and, for POST, the request body. Parameter names come from docs or the spec, spelled exactly: over HTTP most routes ignore an unknown query parameter without an error, so a misspelled filter (`country` for `countries`) returns the default data.
4. Call `https://sugra.ai` with `x-api-key`. Set every parameter the question names (place, identifier, period, frequency, unit). GET uses query params. POST uses JSON body plus any path or query params the spec lists.
5. Parse `{data, meta}`, or the flat object with `meta` / `_meta` that a few payloads return. Check the answer (below), then cite the source and the figure's date (check 4). Read `X-RateLimit-Remaining`.

```
GET https://sugra.ai/api/v1/etf/sectors/relative-strength?window=1m
x-api-key: sugra_...
```

## MCP loop

Works on hosted and stdio. Do not call hosted-only names on stdio. The catalog tools (`search_endpoints`, `describe_endpoint`, `list_toolsets`, `list_sources`) read the catalog bundled with the server and do not call https://sugra.ai; only `call_endpoint`, `fetch_data`, and the entity tools do.

1. `search_endpoints(query=..., toolset=None, source=None, limit=10)`. Unknown `toolset` / `source` returns `unknown_toolset` / `unknown_source` with the valid set, not an empty hit list.
2. Pick an `operation_id` from `results` by its summary, not by its rank: the first hit is not always the measure asked for (a search for an unemployment rate can rank a labour force participation series first). Confirm it on docs.sugra.ai.
3. `describe_endpoint(operation_id=...)` - params with defaults, `request_body_schema` on POST, `agent_hints` (`duration_class`, `max_concurrency`, `bulk_cost`).
4. `call_endpoint(operation_id=..., params={...}, body=...)`. Set every parameter the question names. On the hosted server a key the operation does not declare returns `unknown_parameters` with `accepted` and, when close, `did_you_mean`.

`fetch_data(query=...)` is a one-shot: it calls the top catalog match with the params given. A missing required parameter returns `needs_params` with the selected endpoint and candidates; a missing optional one silently takes its default. Check the answer below before using it; if the operation or the place is wrong, use the four-step loop. `list_toolsets` and `list_sources` (resources `sugra://catalog/domains`, `sugra://catalog/sources`) are the map, not the query.

Shaping on `call_endpoint` / `fetch_data` (`limit`, `fields` as dotted paths, `include_raw`): skill `envelope-and-attribution`.

Hosted only: `resolve_entity`, `get_snapshot`, `get_timeseries`. LEI/VAT and sanctions on every transport: `sugra_entity_lookup`, `sugra_entity_screen`.

The MCP prompts (`market_snapshot`, `macro_briefing`, `sanctions_screening`, `sector_compare`, `earth_conditions`, `source_overview`) are numbered recipes over the gateway tools. They are not the catalog and do not cover every direction. For anything they do not name, use the loop above.

## Check the answer before quoting it

1. `meta.endpoint` is the operation you meant.
2. The place, entity, and period in `data` are the ones asked about, not a default.
3. The measure is the one asked about: a participation rate is not an unemployment rate, a level is not a change, a monthly figure is not an annual one.
4. The figure is dated by an `as_of` (in a record, in `data`, or in `meta`), by `meta.period`, or by a `data_time` the source stated, never by one that fell back to the response time. With none of them, say the source time is unavailable (skill `envelope-and-attribution`).

If any check fails, fix the call. Do not present a near miss as the answer, and do not fill a gap from memory.

## Misses and errors

A miss is not "Sugra has no data". Search docs.sugra.ai. Widen the query. Drop a bad MCP `toolset`/`source` filter. If MCP search still misses, fetch live `/openapi.json` (the wheel catalog can lag), then HTTP-call if the spec has it.

An error message usually names the fix: read it before retrying. A 400 or 422 over HTTPS names the parameter or value to change; over MCP a 422 can arrive as a bare `HTTP 422`. Full table: skill `auth-and-quota`.

Do not add per-endpoint MCP tools to skip this loop. Do not skip `describe_endpoint` when the parameter list is unknown.

## Timeouts

30 seconds covers most GETs. Bulk or live-upstream POSTs can run longer. MCP `agent_hints.duration_class` is the budget hint. A timeout is not empty data.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: envelope-and-attribution
description: Parse Sugra API payloads over HTTPS or MCP, keep source attribution, and tell observation time from request time. Use when reading a response, citing a figure, or shaping a large payload.
license: MIT
---

# Envelope and attribution

The API is LLM-friendly: one JSON envelope `{data, meta}` on most payloads, and the envelope-less exceptions are named below. Envelope detail also lives on https://docs.sugra.ai.

Most responses:

```json
{
  "data": {},
  "meta": {
    "endpoint": "/api/v1/...",
    "data_time": "2026-06-12T19:30:00Z",
    "response_time": "2026-06-12T19:30:01Z",
    "provider": "Sugra API ...",
    "source": "fred",
    "attribution": "<upstream notice, quote it verbatim>",
    "cached": false
  }
}
```

Always present: `endpoint` (the operation that answered), `data_time`, `response_time`, `provider`. Present when they apply:

| Key | Meaning |
|---|---|
| `source` | the upstream source id; name it only when it is a sovereign, intergovernmental, or academic source (Attribution below) |
| `attribution` | a notice the source requires; repeat it word for word wherever the figure is shown |
| `period` | the unit of observation (for example `2026-Q1`) when `data_time` is the start of a period |
| `data_age_days` | days since a time the source itself stated; absent when the source gave only a date or period, or no readable time (Time below) |
| `cached` | served from the platform cache |
| `stale`, `stale_since` | the data is older than it should be; say so when quoting it |
| `fallback_used`, `fallback_chain` | a secondary source answered |
| `notes` | a data quality caveat; pass it on |

Some payloads also carry a `license` inside `data`. Keep it with the figure.

Some payloads are envelope-less (a flat object with `meta` or `_meta` on the same record). Provenance keys still apply.

HTTP: this JSON body plus `X-RateLimit-*` headers.

MCP: `call_endpoint` / `fetch_data` return the same payload (a top-level array is wrapped as `{data: ...}`). `limit` and `fields` shape the records list in `data`, and lists nested inside records are never truncated; `include_raw` attaches the complete original payload under `raw` when it fits the size cap. An object `data` without a records list, or an envelope-less object, counts as one record for `fields`, and `meta` / `_meta` stay. On the hosted server a projection that matches nothing removes nothing, and the records list can also be the one list inside an object `data`, when exactly one of `data`, `entries`, `events`, `history`, `items`, `observations`, `points`, `records`, `results`, `rows`, `series`, `timeseries` holds a list. Keys beside that list, such as `total` and `count`, stay unless a `fields` entry names a key of `data` itself, which projects `data` as one record instead. Stdio packages up to 0.12.0 do not look inside an object `data` for a records list and can return empty records when no field matches. `meta.shaped` reports `fields_applied`, `fields_unmatched`, `limit_applied` and, on the hosted server, `records_path`.

`meta.shaped` reports what shaping actually did, not an echo of the request. On the hosted server `records_path` names the records list that `limit` bounded or that `fields` were matched against (for example `data.items`), even when no field matched, and is null when shaping used no records list. There `limit` keeps the newest end when every record carries one date or period key in one format and the list runs one way by it (the last N of an oldest-first list, the first N of a newest-first one), and otherwise the first N; `meta.shaped` then reports `order` (`asc`, `desc` or `unknown`) and `kept_end` (`newest` or `first`). When `records_path` is `data.*.observations` (several named sub-series side by side, each bounded on its own), `order` and `kept_end` are maps keyed by sub-series name. Before citing the latest figure from a bounded list, check that `kept_end` is `newest`, for a sub-series the value under its name. Stdio packages up to 0.12.0 keep the first N and report neither.

## Time

`data_time` in `meta` (or `_meta` on a flat payload) is the observation or publication time the source states for the data. When the source states no time, or one that cannot be read, `data_time` falls back to the HTTP response time (in `meta` it then equals `response_time`) and `data_age_days` is absent; for a time that cannot be read, `meta.notes` says so. That fallback is the time of the response, not of the data: never present it as the date of a figure, and if it is shown at all, label it the response time. When `meta.period` is present, `data_time` is the start of that period, not a moment of observation. An `as_of` in a record, in `data`, or in `meta` dates the figure itself: a period, a report or snapshot date, or a collection time. When an `as_of` differs from a `data_time` the source stated, quote both. When nothing dates the figure, say the source time is unavailable. Do not describe a delayed series as a live tick, and say so when `stale` is true.

## Attribution

Every figure needs a source and an as-of. Take the source from `meta` / `_meta`, and the date from an `as_of` wherever it sits, `meta.period`, or a `data_time` the source stated (Time above): name the source, give the date or period or say the source time is unavailable, and when `attribution` is present repeat it verbatim. Live list: https://sugra.ai/sources (MCP resource `sugra://attribution`).

- Sovereign, intergovernmental, and academic sources are named openly (for example FRED, IMF, ECB, NOAA, World Bank, SEC EDGAR).
- Commercial upstreams appear under Sugra-branded wrappers (Sugra Finance, Sugra News, Sugra Crypto, Sugra Forex, Sugra Weather). Cite the wrapper, not the vendor, even when `meta.source` carries the vendor's id; a required `attribution` notice is still repeated as given.

This is data presentation, not investment, legal, or compliance advice. Screening tools return a signal, not a determination.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: live-docs
description: Find current Sugra documentation. Use when an endpoint, parameter, default, or version might be stale. Canonical docs are https://docs.sugra.ai (search and Ask AI). Also OpenAPI, /sources, the blog, and MCP tools/list.
license: MIT
---

# Live docs

https://docs.sugra.ai is the external documentation truth. It has search and Ask AI. Per-endpoint parameters, schemas, and examples live in its API Reference sidebar. This skill pack does not copy that catalog.

## How to read docs.sugra.ai

1. Open https://docs.sugra.ai (Welcome: directions, key, envelope, plans, MCP).
2. Search the docs site, or use Ask AI, for the operation or topic.
3. Open the endpoint page in API Reference before calling. Confirm method, path, parameters with their defaults, and body.
4. Pages have a Markdown version at the page URL plus `.md`, and https://docs.sugra.ai/llms.txt indexes them. Prefer those for a compact read.

Do not invent a path. Do not treat this SKILL.md, a README, or a cookbook recipe as the operation list.

## Machine companions (not a second docs site)

| URL | Role |
|---|---|
| `GET https://sugra.ai/openapi.json` | HTTP contract for the call |
| `GET https://sugra.ai/sources` | live source names |
| `GET https://sugra.ai/health` | liveness |

These need no key. Public copy uses hedges (1,600+ endpoints, 160+ sources, 36 domains); quote them as hedges, not as counts. The MCP wheel catalog can lag OpenAPI. If MCP search misses, search docs.sugra.ai, then OpenAPI, then say whether the operation exists.

MCP once connected: `initialize` (`serverInfo.version`), `tools/list`, `prompts/list`, `resources/list`.

## Other public surfaces (search these, not the open web first)

| Where | What |
|---|---|
| https://sugra.ai | product |
| https://sugra.systems | company, legal, API marketing, direction pages |
| https://sugra.systems/blog | blog index; article also as `/{slug}.md`; `llms.txt` |
| https://app.sugra.ai | keys, usage, billing, playground |
| https://app.sugra.ai/register | sign up; a key is issued at signup |
| https://app.sugra.ai/developer/keys | manage keys |
| https://sugra.systems/api/pricing | plans and prices |
| https://docs.sugra.ai/doc-2444801 | ecosystem: MCP package, HTTP recipes, OpenBB provider |

Legal: https://sugra.systems/terms-of-service and sibling policy pages. Contacts: `support@`, `legal@`, `privacy@`, `abuse@` sugra.systems.

Source names: live `/sources`. Sovereign, intergovernmental, and academic names are open. Commercial upstreams appear as Sugra Finance, Sugra News, Sugra Crypto, Sugra Forex, Sugra Weather.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: using-sugra-api
description: Work with the Sugra API over HTTPS and MCP. Use when the task needs Sugra data, a key, product directions (Finance, Macro, Entity, Net Atlas, News, Earth, Research), or which skill to load next.
license: MIT
---

# Using the Sugra API

Sugra API is intelligence infrastructure: one HTTP API, one key, seven product directions. Domain-agnostic. Do not frame it through one vertical.

The surface is LLM-friendly: one `x-api-key`, one JSON envelope `{data, meta}` on most payloads (a few are flat, with `meta` or `_meta` on the record; see envelope-and-attribution), MCP as the agent-native entry. Documentation truth is https://docs.sugra.ai (search and Ask AI). This skill is a map, not the catalog.

These files are English. Reply in the user's language.

Public hedge (not a live count): 1,600+ endpoints, 160+ primary sources, 36 domains. Quote these as "more than", never as an exact figure. The current operation list is `https://sugra.ai/openapi.json` (skill `live-docs`).

## Two complete ways in

| Surface | When | How |
|---|---|---|
| HTTPS `https://sugra.ai` | The agent can GET/POST | `x-api-key` on `/api/v1/...` |
| MCP | The host is an MCP client | the Sugra API MCP server; setup for each client: https://docs.sugra.ai/doc-2263382 |

Both reach the same API. Use the surface the host already has, or the one the user named. Key: sign up at https://app.sugra.ai/register (a key is issued at signup), manage keys at https://app.sugra.ai/developer/keys. Free: 50 requests a day per account. Do not log the key.

## Before quoting a figure

A call that returns data is not yet an answer. Check that `meta.endpoint` is the operation meant, and that the place, entity, period, and measure in `data` are the ones the user asked about. An optional parameter left out takes its default, which can be another country or period; a required one must be set. Details: skill `discover-and-call`.

## Seven directions (one key, one budget)

| Direction | Coverage |
|---|---|
| Sugra Finance | Equities, fundamentals, filings, fixed income, derivatives, crypto, forex |
| Sugra Macro | Central banks, national statistics, FRED, IMF, World Bank, OECD |
| Sugra Entity | Company resolution, sanctions and watchlist screening, identifiers |
| Sugra Net Atlas | Internet infrastructure: ASNs, prefixes, IXPs, routing, DNS |
| Sugra News | Global news flow and event signals |
| Sugra Earth | Weather, hazards, energy, transport, air quality, climate |
| Sugra Research | Scientific, patent, and academic datasets |

## Skill map

| Need | Skill |
|---|---|
| Live docs, search, Ask AI, sources, blog | `live-docs` |
| Key, plans, quota, errors | `auth-and-quota` |
| Find, call, and check an operation (HTTP and MCP) | `discover-and-call` |
| Envelope, sources, clocks, MCP shaping | `envelope-and-attribution` |
| Two or three directions in one answer | `cross-domain-briefing` |

Referenced files: 1 — file references are metadata, not package contents.