# 24TopNews Agent API Guide

Base URL: `https://24topnews.com/api/v1`

Use `lang=en` on every events, event-detail, industries and RSS request. Responses are UTF-8 JSON, except RSS. The API is read-only.

## Authentication

Anonymous requests are supported with shared limits. For an approved API key:

```http
Authorization: Bearer tn_live_your_key
```

Never place a key in a URL, browser bundle, prompt, chat, log or public repository. Read the `X-RateLimit-*` response headers and back off on HTTP 429.

## Recommended agent workflow

1. Resolve an industry code with `GET /industries?lang=en&level=2&q=semiconductor`.
2. List compact events with `GET /events?lang=en&range=24h&industry=10.1&limit=20`.
3. Follow `pagination.next_cursor` while `has_more=true`.
4. Read full text and every quantitative impact only for selected events with `GET /events/{id}?lang=en`.
5. Cite the permanent `url` returned by the API. Treat impact scores as analytical estimates, not investment advice.

## GET /events

Example:

```bash
curl 'https://24topnews.com/api/v1/events?lang=en&range=7d&type=company&industry=10.1&min_importance=80&limit=20' \
  -H 'Authorization: Bearer tn_live_your_key'
```

Query parameters:

- `lang`: `en` for English; omit for Chinese.
- `range`: `24h`, `3d`, `7d`, `20d`, `60d` or `200d`; default `24h`.
- `since`, `until`: ISO 8601 timestamps. `since` replaces the range start; the maximum custom window is 366 days.
- `type`: `all`, `macro`, `domestic_macro`, `global_macro`, `market`, `industry` or `company`.
- `market`: `a-shares`, `hong-kong`, `us-equities`, `commodities` or `other`; omit for all.
- `industry`: a level-two industry code such as `10.1`. Do not send an industry name.
- `direction`: `all`, `positive`, `negative` or `mixed`.
- `min_importance`: 0–100 event importance.
- `min_impact`: 0–100 absolute industry-impact intensity.
- `min_confidence`: 0–100 impact confidence.
- `q`: title, summary or article keyword, maximum 120 characters.
- `include=content`: include full `content_text` in list results. Prefer event detail to reduce payload.
- `limit`: 1–50; default 20.
- `cursor`: copy the previous response's opaque `next_cursor` exactly. Never construct or edit it.

List event fields:

- `id`: stable event UUID.
- `url`: permanent English article URL.
- `type`, `type_label`: machine value and English label.
- `markets`: affected market labels.
- `title`, `summary`, optional `content_text`: English publication text.
- `published_at`, `updated_at`, `first_seen_at`, `last_seen_at`: ISO 8601 timestamps.
- `importance`: 0–100 materiality score.
- `is_key_event`: whether the event is designated as key.
- `source_count`: number of independent source feeds consolidated.
- `impacts`: one object per affected level-two industry. Market-tape events intentionally return no industry impacts.

Impact fields:

- `industry_id`, `industry_name`, `parent_id`, `parent_name`.
- `direction`: `positive`, `negative` or `mixed`.
- `impact`: signed intensity from -100 to 100.
- `confidence`: 0–100.
- `time_horizon`: `immediate`, `short`, `medium` or `long`.
- `channels`: transmission-channel text. It may be empty in English.
- `rationale`: concise English quantitative assessment.

## GET /events/{id}

Returns one full event and all impacts. The path value is the exact UUID returned by `/events`.

```bash
curl 'https://24topnews.com/api/v1/events/REPLACE_WITH_UUID?lang=en'
```

## GET /industries

Parameters:

- `lang=en`
- `level=1`, `level=2` or `level=all`
- `q`: code, English name or parent-industry search

Fields are `id`, `name`, `level`, `parent_id`, `parent_name`, `description` and `url`.

## Full-text RSS

`https://24topnews.com/rss.xml?lang=en&range=24h&limit=50`

RSS accepts the same event filters, up to 100 items, and includes full text in `content:encoded`. API-key authentication uses the same Bearer header when required.

## Errors

- 400: invalid parameter or cursor. Correct the request; do not retry unchanged.
- 401: invalid, revoked or expired API key.
- 403: insufficient scope.
- 404: event not found.
- 429: rate limit or quota reached. Respect `Retry-After`.
- 500: temporary service failure. Retry with exponential backoff and jitter.

## Level-one industries

- `1` Energy
- `2` Mining & Resources
- `3` Chemicals & Materials
- `4` Agriculture
- `5` Food & Beverages
- `6` Manufacturing
- `7` Construction & Real Estate
- `8` Automotive
- `9` Electronic Equipment
- `10` Technology
- `11` Internet & Media
- `12` Consumer & Retail
- `13` Healthcare
- `14` Financials
- `15` Transport & Logistics
- `16` Education, Culture & Travel

## Level-two industry codes

- `1.1` Coal — Energy
- `1.2` Oil & Gas Exploration — Energy
- `1.3` Oilfield Equipment & Services — Energy
- `1.4` Refining & Petrochemicals — Energy
- `1.5` Fuel & Gas Distribution — Energy
- `1.6` Nuclear Power — Energy
- `1.7` Nuclear Equipment — Energy
- `1.8` Thermal Power — Energy
- `1.9` Hydropower — Energy
- `1.10` Wind & Solar Power — Energy
- `1.11` Wind & Solar Equipment — Energy
- `1.12` Power Equipment — Energy
- `1.13` Power Transmission Networks — Energy
- `1.14` Batteries & Energy Storage — Energy
- `2.1` Energy Transition Metals — Mining & Resources
- `2.2` Precious Metals Mining — Mining & Resources
- `2.3` Base Metals — Mining & Resources
- `2.4` Non-metallic Minerals — Mining & Resources
- `2.5` Resource Recycling — Mining & Resources
- `3.1` Basic Chemicals — Chemicals & Materials
- `3.2` Specialty Chemicals — Chemicals & Materials
- `3.3` Electronic Chemicals — Chemicals & Materials
- `3.4` Agrochemicals & Fertilizers — Chemicals & Materials
- `3.5` Pharmaceutical Chemicals — Chemicals & Materials
- `3.6` Basic Building Materials — Chemicals & Materials
- `3.7` Functional Building Materials — Chemicals & Materials
- `3.8` Paper & Pulp — Chemicals & Materials
- `4.1` Crop Production — Agriculture
- `4.2` Fisheries — Agriculture
- `4.3` Livestock — Agriculture
- `5.1` Staple Food Processing — Food & Beverages
- `5.2` Condiments — Food & Beverages
- `5.3` Fresh Produce — Food & Beverages
- `5.4` Convenience Foods — Food & Beverages
- `5.5` Snack Foods — Food & Beverages
- `5.6` Beverages & Dairy — Food & Beverages
- `5.7` Alcoholic Beverages — Food & Beverages
- `5.8` Tobacco — Food & Beverages
- `6.1` Steelmaking — Manufacturing
- `6.2` Textile Manufacturing — Manufacturing
- `6.3` Packaging & Printing — Manufacturing
- `6.4` General Industrial Equipment — Manufacturing
- `6.5` Chemical Processing Equipment — Manufacturing
- `6.6` Food Processing Equipment — Manufacturing
- `6.7` Agricultural Machinery — Manufacturing
- `6.8` Construction Machinery — Manufacturing
- `6.9` Rail Equipment — Manufacturing
- `6.10` Shipbuilding — Manufacturing
- `6.11` Aerospace Manufacturing — Manufacturing
- `6.12` Defence Equipment — Manufacturing
- `7.1` Residential Development — Construction & Real Estate
- `7.2` Commercial Property Development — Construction & Real Estate
- `7.3` Building Construction — Construction & Real Estate
- `7.4` Public Infrastructure Construction — Construction & Real Estate
- `7.5` Industrial Construction — Construction & Real Estate
- `7.6` Municipal Utilities — Construction & Real Estate
- `7.7` Property Brokerage — Construction & Real Estate
- `7.8` Property Management — Construction & Real Estate
- `7.9` Real Estate Investment Trusts — Construction & Real Estate
- `8.1` Auto Parts — Automotive
- `8.2` Conventional Vehicles — Automotive
- `8.3` New Energy Vehicles — Automotive
- `8.4` Automotive Services — Automotive
- `8.5` Light Mobility — Automotive
- `9.1` Electronic Components — Electronic Equipment
- `9.2` Home Appliance Components — Electronic Equipment
- `9.3` Network Equipment — Electronic Equipment
- `10.1` Semiconductor Value Chain — Technology
- `10.2` Internet of Things — Technology
- `10.3` Cloud Services & Data Centres — Technology
- `10.4` Artificial Intelligence — Technology
- `10.5` Robotics — Technology
- `10.6` General Software & IT Services — Technology
- `10.7` Enterprise Software — Technology
- `10.8` Professional Services — Technology
- `11.1` Telecom Operators — Internet & Media
- `11.2` Digital Marketing — Internet & Media
- `11.3` Social Media — Internet & Media
- `11.4` Streaming Media — Internet & Media
- `11.5` Video Games — Internet & Media
- `11.6` Diversified Internet Platforms — Internet & Media
- `11.7` Local Consumer Platforms — Internet & Media
- `12.1` Home Appliances — Consumer & Retail
- `12.2` Computers & Servers — Consumer & Retail
- `12.3` Smartphones — Consumer & Retail
- `12.4` Consumer Electronics — Consumer & Retail
- `12.5` Apparel & Footwear — Consumer & Retail
- `12.6` Household Products — Consumer & Retail
- `12.7` Home Improvement — Consumer & Retail
- `12.8` Sporting Goods — Consumer & Retail
- `12.9` Pet Care — Consumer & Retail
- `12.10` Jewellery & Watches — Consumer & Retail
- `12.11` Designer Toys — Consumer & Retail
- `12.12` Luxury Goods — Consumer & Retail
- `12.13` Pharmacy Retail — Consumer & Retail
- `12.14` Physical Retail — Consumer & Retail
- `12.15` Duty-free Retail — Consumer & Retail
- `12.16` Domestic E-commerce — Consumer & Retail
- `12.17` Cross-border E-commerce — Consumer & Retail
- `13.1` Pharmaceuticals — Healthcare
- `13.2` Traditional Chinese Medicine — Healthcare
- `13.3` Biotechnology — Healthcare
- `13.4` Medical Consumables — Healthcare
- `13.5` Medical Equipment — Healthcare
- `13.6` General Hospitals — Healthcare
- `13.7` Specialist Hospitals — Healthcare
- `13.8` Telemedicine — Healthcare
- `13.9` Health Management & Diagnostics — Healthcare
- `13.10` Medical Aesthetics — Healthcare
- `13.11` Nutrition & Supplements — Healthcare
- `13.12` Personal Health & Hygiene — Healthcare
- `13.13` Cosmetics — Healthcare
- `13.14` Elderly Care — Healthcare
- `13.15` Pharmaceutical R&D Services — Healthcare
- `14.1` State-owned Banks — Financials
- `14.2` Commercial Banks — Financials
- `14.3` Regional Banks — Financials
- `14.4` Securities Firms — Financials
- `14.5` Public Funds — Financials
- `14.6` Private Equity & Venture Capital — Financials
- `14.7` Life Insurance — Financials
- `14.8` Property & Casualty Insurance — Financials
- `14.9` Reinsurance — Financials
- `14.10` Diversified Financials — Financials
- `14.11` Financial Technology — Financials
- `14.12` Payment Services — Financials
- `14.13` Digital Assets & Blockchain — Financials
- `15.1` Road Transport — Transport & Logistics
- `15.2` Rail Transport — Transport & Logistics
- `15.3` Shipping & Ports — Transport & Logistics
- `15.4` Air Transport — Transport & Logistics
- `15.5` Logistics & Express Delivery — Transport & Logistics
- `16.1` Primary & Secondary Education — Education, Culture & Travel
- `16.2` Vocational Education — Education, Culture & Travel
- `16.3` Publishing & Broadcasting — Education, Culture & Travel
- `16.4` Film & Entertainment — Education, Culture & Travel
- `16.5` Tourism — Education, Culture & Travel
- `16.6` Hotels — Education, Culture & Travel
- `16.7` Restaurants — Education, Culture & Travel