Crypto News Http Api

SKILL.md

---
name: crypto-news-http-api
description: Use when calling the Crypto News Analyzer HTTP API for async analysis jobs, semantic search, datasource management, intelligence operations, or health checks from OpenClaw.
metadata: { openclaw: { skillKey: crypto-news-http-api, primaryEnv: API_KEY } }
---

# Crypto News HTTP API Skill

Use this skill to call the Crypto News Analyzer HTTP API from OpenClaw.

## When to Use

Use this skill when you need to call `https://news.tradao.xyz` or a compatible private deployment.

Typical triggers:

- Run asynchronous crypto news analysis over a time window
- Run asynchronous semantic search for a freeform topic query
- Poll an API job until it finishes and then fetch the final result
- Create, list, or delete datasources through the HTTP API
- Query and manage hidden-channel intelligence entries (discovery, follow states, semantic search, raw evidence)
- List, inspect, and converge intelligence topics that group canonical entries
- Check service health before or after an API workflow

## Quick Reference

Authentication is Bearer token style: send `Authorization: Bearer <API_KEY>` with every request.

`POST /analyze` creates a job and returns immediately. It does **not** return the final report. Poll status, then fetch the result.

Workflow: `POST /analyze` -> `GET /analyze/{job_id}` -> `GET /analyze/{job_id}/result`

Jobs move through these states: `queued`, `running`, `completed`, `failed`.

`POST /semantic-search` creates a job, returns `202 Accepted`, and includes `status_url`, `result_url`, plus a `Retry-After` header.

Semantic workflow: `POST /semantic-search` -> `GET /semantic-search/{job_id}` -> `GET /semantic-search/{job_id}/result`

Semantic search requires PostgreSQL with pgvector. SQLite runtime is unsupported.

For detailed guides, see:

- [Analyze Workflow Reference](references/analyze-workflow.md)
- [Semantic Search Reference](references/semantic-search.md)
- [Datasource Management Reference](references/datasource-management.md)
- [Intelligence Query Reference](references/intelligence-query.md)
- [Operations and Maintenance Reference](references/operations-and-maintenance.md)

## OpenClaw Runtime

This skill declares `metadata.openclaw.primaryEnv: API_KEY`. In OpenClaw, inject the bearer token through `~/.openclaw/openclaw.json`:

```json5
{
  skills: {
    entries: {
      "crypto-news-http-api": {
        enabled: true,
        apiKey: "YOUR_API_KEY"
      }
    }
  }
}
```

If `apiKey` is unavailable, do not send unauthenticated requests. Ask the operator to configure the token first.

If you are using a non-production deployment, replace `https://news.tradao.xyz` with the correct base URL before issuing requests.

## Analyze Workflow

Create an analysis job by posting to `/analyze` with `hours` and `user_id`. The server responds with `202 Accepted`, a `job_id`, `status_url`, and `result_url`.

Poll the status endpoint until the job reaches `completed` or `failed`. Do not expect the analysis report in the initial POST response. Once completed, fetch the result URL.

## Semantic Search

Create a semantic search job by posting to `/semantic-search` with `hours`, `query`, and `user_id`. The server responds with `202 Accepted`, a `job_id`, `status_url`, and `result_url`. Semantic search job IDs start with `semantic_search_job_`.

Poll the status endpoint until the job reaches `completed` or `failed`, then fetch the report from the result URL. Use the `status` field as the source of truth for lifecycle state; `success` becomes `true` only when the job is completed successfully.

Request rules:

- `hours` must be a positive integer
- `query` is required, trimmed, and capped at 300 characters
- `query` cannot be blank or whitespace-only
- `user_id` must match `^[A-Za-z0-9_-]{1,128}$`

Operational constraints:

- Semantic search is PostgreSQL-only and returns `503` when the backend does not support pgvector
- The API uses vector similarity over stored content embeddings and may combine that with keyword retrieval
- Query decomposition is capped at 4 subqueries
- Final retained results are capped at 200 unique items
- Embedding generation requires `OPENAI_API_KEY`; query planning and report synthesis require `KIMI_API_KEY` or `GROK_API_KEY`

The result body returns a Markdown report with `query`, `normalized_intent`, `matched_count`, `retained_count`, `time_window_hours`, and `report`.

## Datasource Management

Configure news sources through the datasource API. Create sources with `POST /datasources`, list them with `GET /datasources`, and remove them with `DELETE /datasources/{id}`. All datasource routes require Bearer auth.

Tags help organize sources. Each datasource accepts up to 16 unique tags. Each tag is capped at 32 characters. Tags are normalized to lowercase and deduplicated automatically.

List responses include only safe summaries. For `rest_api` type datasources, secrets are redacted and counts replace raw credential fields. This prevents accidental credential exposure when reviewing configurations.

## Intelligence Query

Query and manage the hidden-channel intelligence knowledge base built by the private ingestion pipeline. All intelligence routes require Bearer auth.

Synchronous endpoints provide access to canonical knowledge entries, discovery candidates, searchable labels, and raw evidence:

- `GET /intelligence/entries` — List canonical entries with time window, type, label, and `tracking_scope` filters, paginated
- `GET /intelligence/discovery` — List entries whose follow status is unset
- `GET /intelligence/labels` — List searchable primary labels
- `GET /intelligence/entries/{entry_id}` — Get a single entry with optional latest raw evidence (`include_raw=true`) plus paginated evidence context groups
- `POST /intelligence/entries/{entry_id}/follow-status` — Set an entry's follow status to `follow`, `unfollow`, or `unset`
- `GET /intelligence/search` — Semantic search using required `q` parameter, ranked by vector similarity plus repository scoring, paginated
- `GET /intelligence/raw/{raw_item_id}` — Get original raw text for a collected item (30-day TTL)

These endpoints are synchronous; there is no async job/poll flow. Results return immediately.

Raw text is byte-for-byte original within the TTL window. After expiration, `raw_text` is `null` and `is_expired` is `true`. Canonical structured knowledge remains queryable indefinitely.

The `window` parameter accepts `<N>h` (hours) or `<N>d` (days), e.g. `7d`, `24h`; invalid values are ignored by the current implementation. Entry types are `channel` and `slang`. Primary labels are `AI`, `crypto`, `DARK_WEB`, `ACCOUNT_TRADING`, `PAYMENT`, `GAME`, `ECOMMERCE`, `SOCIAL_MEDIA`, `DEVELOPER_TOOLS`, and `OTHER` values; see the reference for exact API string values.

The `tracking_scope` parameter is supported by `/intelligence/entries` and `/intelligence/search`. Valid values are `following`, `discovery`, `unset`, `unfollowed`, and `all`; default is `following`. Invalid values return `400`.

Canonical entries use a follow state of `follow`, `unfollow`, or `unset`. Newly collected slang and channel entries default to `unset`.

For full parameter details, response schemas, and examples, see the [Intelligence Query Reference](references/intelligence-query.md).

## Intelligence Topics

Topics automatically group followed canonical entries to reduce noise in `/intel_recent` and enable LLM-based deep-dive enrichment. Topic routes are synchronous and Bearer-protected.

- `GET /intelligence/topics` — List active topics with entry counts, paginated. Query `active_only=false` to include inactive (merged) topics.
- `GET /intelligence/topics/{topic_id}` — Get topic detail including enriched summary, source channels, methods, vulnerabilities, latest findings, linked entries, and recent run logs.
- `GET /intelligence/topic-runs` — List topic run logs (auto_link, enrich, converge). Filter by `topic_id` or `run_type`.
- `POST /intelligence/topics/converge` — Trigger LLM-based topic convergence. Merges similar topics using embedding similarity + LLM confirmation. Returns `merged_count` and `skipped`.

When you follow an entry via `POST /intelligence/entries/{entry_id}/follow-status` with `"follow_status":"follow"`, the system automatically assigns it to a topic. The response may include optional `topic` and `topic_error` fields reflecting the topic assignment result.

When you unfollow an entry, its `topic_id` is cleared. If the topic has no remaining linked entries, it is automatically deactivated.

For full topic response schemas and examples, see the [Intelligence Query Reference](references/intelligence-query.md).

## Telegram Webhook

The webhook endpoint exists for maintainer-level Telegram integration. It is not the primary path for day-to-day operators. Regular users should interact through the API routes or Telegram slash commands instead.

When processing webhook updates, validate the `X-Telegram-Bot-Api-Secret-Token` header to confirm the request originates from Telegram.

## Endpoint Index

Supported HTTP routes:

- `GET /health` - Service health check
- `POST /analyze` - Create an analysis job (async, returns 202)
- `GET /analyze/{job_id}` - Check job status
- `GET /analyze/{job_id}/result` - Retrieve completed job results
- `POST /semantic-search` - Create a semantic search job (async, returns 202)
- `GET /semantic-search/{job_id}` - Check semantic search job status
- `GET /semantic-search/{job_id}/result` - Retrieve completed semantic search results
- `POST /datasources` - Create a datasource
- `GET /datasources` - List all datasources
- `DELETE /datasources/{id}` - Delete a datasource
- `POST /telegram/webhook` - Telegram webhook receiver
- `GET /intelligence/entries` - List intelligence entries (synchronous, Bearer-protected)
- `GET /intelligence/discovery` - List entries whose follow status is unset
- `GET /intelligence/labels` - List searchable intelligence primary labels
- `GET /intelligence/entries/{entry_id}` - Get intelligence entry detail with optional raw evidence
- `POST /intelligence/entries/{entry_id}/follow-status` - Set intelligence entry follow status
- `GET /intelligence/search` - Semantic search across intelligence entries (paginated with `page`/`page_size`)
- `GET /intelligence/raw/{raw_item_id}` - Get raw intelligence item by ID
- `GET /intelligence/topics` - List intelligence topics with entry counts
- `GET /intelligence/topics/{topic_id}` - Get topic detail with linked entries and run logs
- `GET /intelligence/topic-runs` - List topic run logs with optional filters
- `POST /intelligence/topics/converge` - Trigger topic convergence (merges similar topics via LLM)

## Non-Goals

This skill does not cover:

- Telegram slash commands (use the Telegram bot directly)
- Autogenerated documentation routes (`/docs`, `/redoc`, `/openapi.json`)
- Deprecated compatibility aliases (`api-server`, `crypto-news-api`)
- Direct embedding backfill operations beyond pointing you to the documented command

These surfaces exist but are intentionally excluded from this API-focused skill.

## Updating

Keep this skill aligned with the live HTTP routes in `api_server.py`, `tests/test_intelligence_api.py`, the AI Analyze API Guide at `docs/AI_ANALYZE_API_GUIDE.md`, and the semantic search guide at `docs/SEMANTIC_SEARCH_API_GUIDE.md`.

When documentation disagrees with implementation, trust the code and tests over prose docs. Source precedence: code and tests first, then reference files, then guides.