Sugra API platform intro: one key, seven directions

Series: Sugra product directions (platform foundation)
Audience: developers building on https://sugra.ai over HTTP
Auth: x-api-key header on data endpoints
Live checks: health and envelope patterns verified 2026-07-24

This is the first article in the series. Read it before the direction deep-dives if you are new to the API. It covers authentication, the response envelope, rate limits, plans, public system endpoints, and how the seven directions fit together - without replacing the per-direction use cases that follow.

Series table of contents

Read in order for a full tour, or jump to any standalone piece.

Foundation

#	Article	What you learn
0	This page - Platform intro	Auth, envelope, limits, plans, how the series is organized
1	Sugra Finance	Markets, indicators, 13F, multi-asset wrappers
2	Sugra Macro	Official economic record (FRED, BIS, Treasury, …)
3	Sugra Entity	KYB / sanctions / PEP - signal, not determination
4	Sugra NetAtlas	IP, ASN, BGP, RPKI, Tor, CT
5	Sugra News	Curated headlines, GDELT, Wikipedia attention
6	Sugra Earth	Weather, hazards, grid, aviation, AQ
7	Sugra Research	arXiv, Crossref, Maddison, PWT, NBER

Composition (after all direction overviews)

#	Article	Directions combined
8	Macro + Finance desk	Macro, Finance
9	Compliance + media pulse	Entity, News
10	Physical ops stack	Earth (multi-module)
11	Event stack	Finance, News, Macro

Close

#	Article	What you learn
12	Conclusion	Decision guide, when to use which direction, next steps

Utility and Niche catalog slices are plumbing or de-emphasized product areas. They are not separate headline articles in this series.

What Sugra API is

Sugra is intelligence infrastructure: one API product with seven named product directions behind a single key. You integrate over HTTPS. Plans differ by daily request volume, not by which endpoints you may call - all directions are available on Free, Dev, Pro, and Enterprise (Enterprise volume is custom).

Surface	Role
`https://sugra.ai`	API host
`https://sugra.systems/api/family`	Public family overview of directions
`https://app.sugra.ai`	Account, keys, hosted MCP for agent UIs
sugra-api-cookbook	Runnable Python recipes

This series is written for application developers calling the API directly. Hosted MCP (https://app.sugra.ai/mcp) is for users who wire agents in a chat UI - it is not required for code integration and is not the focus of the direction articles.

Authentication

Data endpoints

Send your key on every data request:

GET /api/v2/quotes/NVDA/price HTTP/1.1
Host: sugra.ai
x-api-key: YOUR_API_KEY

export SUGRA_API_KEY="YOUR_API_KEY"

curl -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/quotes/NVDA/price"

import os
import requests

BASE = "https://sugra.ai"
H = {"x-api-key": os.environ["SUGRA_API_KEY"]}

def get(path, **params):
    r = requests.get(f"{BASE}{path}", headers=H, params=params, timeout=30)
    r.raise_for_status()
    body = r.json()
    return body.get("data", body), body.get("meta", {}), r.headers

Never commit keys. Rotate keys in the app if they appear in chat logs or tickets.

Public system endpoints (no key)

Path	Purpose
`GET /health`	Liveness / basic service status
`GET /sources`	Named source catalog (JSON list)
`GET /about`	About / system info surface (may be HTML or JSON depending on route)

Example:

curl -s "https://sugra.ai/health"
curl -s "https://sugra.ai/sources"

Response envelope

Standard shape (most directions)

{
  "data": { },
  "meta": {
    "endpoint": "/api/v1/fred/series/CPIAUCSL",
    "data_time": "2026-07-24T18:00:46Z",
    "response_time": "2026-07-24T18:00:46Z",
    "provider": "Sugra API v1.0.1",
    "source": "fred",
    "cached": false
  }
}

Field	Use
`data`	Payload your app consumes
`meta.endpoint`	Which route answered
`meta.data_time`	Freshness of the underlying observation when provided
`meta.source`	Provenance label for citation and debugging
`meta.cached`	Whether the platform served a cached copy

Always surface meta.source and meta.data_time in agent answers and research UIs. That is how Sugra stays glass-box relative to model memory.

Envelope exception: NetAtlas

Many /api/v1/network/* lookups return the resource object at the top level with an inline _meta block (product, atlas build time, sources, confidence). See Sugra NetAtlas. Write clients that tolerate both shapes.

Entity disclaimers

Entity screening responses carry meta.disclaimer and often screening_id / list_freshness. Show the disclaimer in product UI. See Sugra Entity.

Rate limits and plans

Limits are per API key, per UTC day, by plan volume. Endpoint access is not gated by plan - only how many billable requests you may make.

Indicative public tiers (confirm on account / monetization docs for the latest numbers):

Plan	Daily volume (order of magnitude)
Free	50 requests / day
Dev	5,000 / day
Pro	50,000 / day
Enterprise	Custom

Headers on data responses

Header	Meaning
`X-RateLimit-Limit`	Your plan’s daily ceiling
`X-RateLimit-Remaining`	Requests left today
`X-RateLimit-Reset`	When the daily counter resets (UTC midnight semantics)
`X-RateLimit-Cost`	Cost of this call when weighted / batch billing applies

On over-limit: HTTP 429 with Retry-After toward the next UTC day boundary (not a fixed one-hour window).

r = requests.get(url, headers=H, timeout=30)
print(r.headers.get("X-RateLimit-Limit"))
print(r.headers.get("X-RateLimit-Remaining"))
print(r.headers.get("X-RateLimit-Reset"))
if r.status_code == 429:
    # back off until reset; do not tight-loop
    pass

Batch and cost

Some batch endpoints bill per item inside the body (for example batch screens), not one unit per HTTP request. Read X-RateLimit-Cost and the monetization docs before designing high-N batch jobs on Free tier.

Practical budgeting for this series

Pattern	Rough call count
Single flagship probe	1
Direction use case (2-6 calls)	low tens
Macro regime monitor recipe	~6
Multi-direction composition	5-15 sequential
Naive per-symbol loops	can exhaust Free quickly - prefer batch endpoints

Cookbook: 12_patterns_rate_limits.py, 13_patterns_pagination.py.

Errors you should handle

Status	Typical meaning	Client action
401 / 403	Missing or invalid key	Fix auth
404	Wrong path or unknown resource	Check OpenAPI / this series’ live path notes
429	Daily quota exhausted	Stop; wait for reset
503	Upstream or ingest temporarily unavailable	Retry with backoff; keep last-good cache (GDELT timelines, some aviation blobs)

Direction articles document known flaky routes (for example GDELT timeline, some optional NBER paths).

One key, seven directions

                    +------------------+
                    |   x-api-key      |
                    |   one credential |
                    +--------+---------+
                             |
     +-----------+-----------+-----------+-----------+
     |           |           |           |           |
 Finance      Macro       Entity     NetAtlas     News
     |           |           |           |           |
 Earth       Research     (+ Utility plumbing, not headline)

Direction	Question it answers
Finance	What is the market / filing / indicator picture?
Macro	What does the official economic record say?
Entity	What is the screening signal for this name / LEI / wallet?
NetAtlas	What is this IP / ASN / prefix / domain on the internet?
News	What was published / what is media talking about / what has attention?
Earth	What is the physical environment and infrastructure doing?
Research	What do papers and long-run development data say?

Deep-dives: articles 1-7. How to combine them in one client workflow: articles 8-11. Decision guide: Conclusion.

Minimal first successful call

# 1) Public health
curl -s "https://sugra.ai/health"

# 2) Authenticated data call (Finance example)
curl -s -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v2/quotes/NVDA/price"

# 3) Inspect rate-limit headers (use -i)
curl -s -i -H "x-api-key: $SUGRA_API_KEY" \
  "https://sugra.ai/api/v1/fred/series/CPIAUCSL?limit=1" | head -n 20

If step 2 returns a data + meta JSON object, your key and integration path work. Continue to the direction that matches your product.

Copy and product posture (short)

Positioning: intelligence infrastructure, not “financial intelligence”
Not investment advice (especially Finance and any market-adjacent News)
Entity: screening signal, not a determination
Public marketing: Sugra wrappers (Finance / News / Crypto / Forex / Weather) instead of commercial Tier C vendor brand names
Prefer factual cadences (“every 5 minutes”, “daily atlas”) over vague “real-time” claims

Full rules live in Sugra copy documentation; this series follows them.

External references

Family page: https://sugra.systems/api/family
Cookbook quickstart: https://github.com/Sugra-Systems/sugra-api-cookbook/blob/main/recipes/01_quickstart.py
Portal docs (auth, errors, direction pages) on the Sugra API documentation host
Account and keys: https://app.sugra.ai

Seven directions. One key.