---
title: "Seven directions. One key."
description: "How the Sugra API is organized: authentication, envelope, rate limits, and seven named product directions behind one key."
slug: platform-intro
status: published
published_at: 2026-05-12
author: Arman Obosyan
author_url: https://sugra.systems/about
section: foundation
series_order: 0
primary_keyword: sugra api seven directions
hero_image: /blog/images/posts/platform-intro-hero.jpg
hero_alt: "Seven directions. One key. - Sugra API blog"
og_image: /blog/images/posts/platform-intro-hero.jpg
tags:
  - platform
  - api
  - getting-started
---

# 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](/blog/sugra-finance) | Markets, indicators, 13F, multi-asset wrappers |
| 2 | [Sugra Macro](/blog/sugra-macro) | Official economic record (FRED, BIS, Treasury, ...) |
| 3 | [Sugra Entity](/blog/sugra-entity) | KYB / sanctions / PEP - signal, not determination |
| 4 | [Sugra NetAtlas](/blog/sugra-netatlas) | IP, ASN, BGP, RPKI, Tor, CT |
| 5 | [Sugra News](/blog/sugra-news) | Curated headlines, GDELT, Wikipedia attention |
| 6 | [Sugra Earth](/blog/sugra-earth) | Weather, hazards, grid, aviation, AQ |
| 7 | [Sugra Research](/blog/sugra-research) | arXiv, Crossref, Maddison, PWT, NBER |

### Composition (after all direction overviews)

| # | Article | Directions combined |
|---|---|---|
| 8 | [Macro + Finance desk](/blog/compose-macro-finance) | Macro, Finance |
| 9 | [Compliance + media pulse](/blog/compose-entity-news) | Entity, News |
| 10 | [Physical ops stack](/blog/compose-earth-ops) | Earth (multi-module) |
| 11 | [Event stack](/blog/compose-event-stack) | Finance, News, Macro |

### Close

| # | Article | What you learn |
|---|---|---|
| 12 | [Conclusion](/blog/series-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](https://github.com/Sugra-Systems/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:

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

```bash
export SUGRA_API_KEY="YOUR_API_KEY"

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

```python
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:

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

---

## Response envelope

### Standard shape (most directions)

```json
{
  "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](/blog/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](/blog/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).

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

```text
                    +------------------+
                    |   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](/blog/series-conclusion).

---

## Minimal first successful call

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

---

## Read next

**Recommended path for new developers**

1. Finish this platform intro (you are here).  
2. Open the direction that matches your first feature: most product teams start with [Finance](/blog/sugra-finance) or [Macro](/blog/sugra-macro).  
3. Read the other direction articles as needed - each is self-contained.  
4. When you need multi-domain workflows, continue to [compositions](/blog/compose-macro-finance) and the [conclusion](/blog/series-conclusion).

**Immediate next article in series order**

-> [01 - Sugra Finance](/blog/sugra-finance)

**Jump links**

- [Macro](/blog/sugra-macro) · [Entity](/blog/sugra-entity) · [NetAtlas](/blog/sugra-netatlas) · [News](/blog/sugra-news) · [Earth](/blog/sugra-earth) · [Research](/blog/sugra-research)  
- [Compositions start](/blog/compose-macro-finance) · [Conclusion](/blog/series-conclusion)  
- Index: [README](/blog)

---

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