# 大案牍库 (The Grand Archive) — Agent Integration Guide

> **Base URL:** `https://dak-news.com`
>
> A real-time news database tracking 20+ authoritative sources across finance, geopolitics, tech, and social trending. Updated every 30 minutes.

## Quick Start

No SDK or CLI installation required. Just use HTTP requests.

```bash
# Search for news
curl "https://dak-news.com/api/search?q=tariff&limit=5"

# Browse recent entries
curl "https://dak-news.com/api/feeds?category=finance&limit=10"

# Get stats
curl "https://dak-news.com/api/stats"
```

## API Reference

### GET /api/search

Full-text search across all entries. Supports fuzzy and prefix matching.

**Parameters:**

| Parameter  | Type   | Required | Description |
|-----------|--------|----------|-------------|
| q         | string | ✅       | Search query (min 1 char) |
| category  | string | optional | Filter: `finance`, `news`, `tech`, `social` |
| source    | string | optional | Filter by source name (e.g. `Bloomberg`, `CNBC`) |
| from      | string | optional | Start date (ISO 8601, e.g. `2026-04-01`) |
| to        | string | optional | End date (ISO 8601) |
| limit     | number | optional | Results per page (1–100, default 20) |
| offset    | number | optional | Pagination offset (default 0) |

**Example:**

```bash
curl "https://dak-news.com/api/search?q=oil+prices&category=finance&from=2026-04-01&limit=10"
```

**Response:**

```json
{
  "results": [
    {
      "id": "entry-id",
      "title": "Oil prices surge amid Middle East tensions",
      "source": "Bloomberg",
      "category": "finance",
      "published": "2026-04-20T08:30:00Z",
      "score": 8.4
    }
  ],
  "total": 142,
  "query": "oil prices",
  "tier": "anonymous",
  "tierCutoff": "2026-03-28"
}
```

### GET /api/feeds

Browse entries with filtering. No search query required.

**Parameters:**

| Parameter  | Type   | Required | Description |
|-----------|--------|----------|-------------|
| category  | string | optional | Filter by category |
| source    | string | optional | Filter by source |
| from      | string | optional | Start date (ISO 8601) |
| to        | string | optional | End date (ISO 8601) |
| limit     | number | optional | Results per page (1–100, default 20) |
| offset    | number | optional | Pagination offset (default 0) |

**Example:**

```bash
curl "https://dak-news.com/api/feeds?category=tech&limit=5"
```

**Response:**

```json
{
  "entries": [
    {
      "id": "entry-id",
      "title": "Article title",
      "content": "Full article content...",
      "url": "https://original-source.com/article",
      "source": "Hacker News",
      "category": "tech",
      "tags": ["AI", "startup"],
      "author": "author-name",
      "language": "en",
      "published": "2026-04-20T10:00:00Z"
    }
  ],
  "total": 500
}
```

### GET /api/feeds/:id

Get a single entry by ID.

```bash
curl "https://dak-news.com/api/feeds/ENTRY_ID"
```

### GET /api/stats

Get database statistics.

```bash
curl "https://dak-news.com/api/stats"
```

**Response:**

```json
{
  "total": 38254,
  "byCategory": [
    { "category": "finance", "count": 15000 },
    { "category": "news", "count": 12000 }
  ],
  "bySource": [
    { "source": "Bloomberg", "count": 3500 },
    { "source": "CNBC", "count": 2800 }
  ],
  "lastUpdated": "2026-04-25T12:00:00Z"
}
```

### GET /api/feeds/status

Get per-source ingestion status with daily activity bins.

## Access Tiers

| Tier       | History Window | Rate Limit     | Auth Required |
|-----------|---------------|----------------|---------------|
| Anonymous  | 28 days       | 10 req/min     | No            |
| Free       | 90 days       | 60 req/min     | API Key or session |
| Premium    | Unlimited     | 120 req/min    | API Key or session |

### Authentication

**Anonymous:** No headers needed. Limited to recent 28 days.

**API Key:** Sign up at [dak-news.com/signup](https://dak-news.com/signup), then create an API key at [dak-news.com/api-keys](https://dak-news.com/api-keys). Pass it via header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" "https://dak-news.com/api/search?q=inflation"
```

### Rate Limit Headers

Every API response includes:

- `X-RateLimit-Limit` — max requests per minute
- `X-RateLimit-Remaining` — remaining requests this window
- `X-RateLimit-Reset` — Unix timestamp when the window resets

If rate-limited, you receive HTTP 429 with a JSON body.

## Available Sources

**Finance / Macro:** Bloomberg, CNBC, MarketWatch, 华尔街见闻, 第一财经, 财新网, ZeroHedge, 金十数据, 雪球

**International / Geopolitics:** BBC Chinese, NYT Chinese, Al Jazeera, AP News, Foreign Affairs, The Diplomat, 参考消息, 人民网

**Tech:** Hacker News

**Social Trending:** Weibo Hot, Zhihu Hot

## Categories

`finance` `news` `tech` `social`

## Tips for AI Agents

1. **Start with stats** — call `/api/stats` first to understand available data volume and sources.
2. **Use date filters** — narrow results with `from` and `to` to stay within your tier's history window.
3. **Combine filters** — use `category` + `source` + date range for precise queries.
4. **Paginate** — use `offset` to retrieve more than the first page of results.
5. **Check tier info** — the `tier` and `tierCutoff` fields in search responses tell you your current access level.