# Hypeless API

A simple REST API with JSON answers. Every story names its outlet and links to the original. We show headlines, short descriptions and our own summaries, never full articles, and never buy, sell or hold advice.

Live guide: https://hypeless.in/developers · OpenAPI file: https://hypeless.in/openapi.json

## Quick start

1. Sign in with Google and make a key on https://hypeless.in/developers (it is shown once: copy it).
2. Send it as a Bearer token in the Authorization header.
3. Call any endpoint below. The first calls each day are free.

## Base address

`https://hypeless.in/api/v1`

Authentication: Authorization: Bearer hl_live_... on every call. Keep the key secret and never put it in a website or app that other people can open. Keys start with `hl_live_`.

## Prices

- The first 50 calls each day (India time) are free.
- After that, ₹0.50 per call (news, story, tip check).
- Ask Hypeless (AI): ₹2.00 per question.
- Prepaid credit packs are bought on https://hypeless.in/developers.

## Example: the latest stories about one company

```bash
curl "https://hypeless.in/api/v1/news?q=Infosys&limit=5" \
  -H "Authorization: Bearer hl_live_YOUR_KEY"
```

```javascript
const res = await fetch("https://hypeless.in/api/v1/news?q=Infosys&limit=5", {
  headers: { Authorization: "Bearer " + process.env.HYPELESS_KEY },
});
const data = await res.json();
console.log(data.stories[0].outlet, data.stories[0].headline);
```

```python
import os, requests

r = requests.get(
    "https://hypeless.in/api/v1/news",
    params={"q": "Infosys", "limit": 5},
    headers={"Authorization": "Bearer " + os.environ["HYPELESS_KEY"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["stories"][0]["headline"])
```

## Endpoints

Every response includes our disclaimer. The full format is at /api/v1. Each response also sends the headers X-Free-Calls-Left, X-Charged-Paise and X-Credit-Balance-Paise.

### GET /news

Latest Indian market stories from named outlets, with links and the Quick read.

| Input | What it is |
|---|---|
| `q` | Company name to search for (optional) |
| `category` | markets, companies, ipos, economy, banking, commodities, funds, global, tech, auto, pharma or energy (optional) |
| `limit` | How many stories, 1 to 50 (default 20) |
| `summary` | 1 adds today's short market summary (optional) |

```bash
curl "https://hypeless.in/api/v1/news?q=Infosys&limit=5" \
  -H "Authorization: Bearer hl_live_YOUR_KEY"
```

### GET /story/{code}

One story: every outlet's headline, with links.

| Input | What it is |
|---|---|
| `code` | A story code from the news answer (the end of its storyPage link) |

### POST /tip-check

A rule-based check of a stock tip post (its wording), never the stock. No AI.

| Input | What it is |
|---|---|
| `text` | The post to check, up to a few thousand characters (JSON body) |

```bash
curl -X POST "https://hypeless.in/api/v1/tip-check" \
  -H "Authorization: Bearer hl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Guaranteed 300% returns in 2 weeks. Join my group now."}'
```

### POST /ask

Ask Hypeless: answers only from named outlets' recent headlines. Uses AI. (₹2.00 per question)

| Input | What it is |
|---|---|
| `question` | Your question about Indian market news (JSON body) |

```bash
curl -X POST "https://hypeless.in/api/v1/ask" \
  -H "Authorization: Bearer hl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What did outlets report about TCS results?"}'
```

## Errors

| Status | Error | Meaning |
|---|---|---|
| 401 | `missing_or_bad_key / invalid_key` | No key, a wrong key, or a key that was revoked. |
| 402 | `out_of_credits` | No credit left for this call. Buy a pack on this page. The call is not counted. |
| 403 | `plan_has_no_ai` | Your plan does not include the AI endpoint. |
| 429 | `daily_limit / daily_ai_limit` | The key used all its calls for today (India time). They return at midnight. |
| 503 | `unavailable / not_configured` | A problem on our side. Try again in a minute. |

Every answer is JSON with an error name you can test for. Each response also reports your calls today and free calls left in headers. Educational data, not investment advice.

## Rules

The API follows the same rules as Hypeless: no buy, sell or hold views, no stock ratings, and only headlines and links from named outlets, never full articles. Show the outlet's name and link with every story you use.

---
Educational tool, not investment advice. Hypeless is not registered with SEBI and gives no buy, sell or hold views.