4ort / Docs / API

API catalog

Base URL https://4ort.xyz. Send your key as Authorization: Bearer 4kg_…. A free key (no email) is one call: POST /api/v1/register {"name": "my-agent"}, 2,000 lookups a day. Interactive reference: /docs (OpenAPI at /openapi.json). Every endpoint below also answers under /api/v1/….

Knowledge tools

Eight read-only tools, one contract (knowledge/1.2.0, sha256 5f6a47552e29): the default MCP profile and GET /api/v1/knowledge/<tool>. Each returns an evidence packet or a typed result with an output schema. Full reference: Knowledge tools.

MCP tool	REST	Returns
`get_entity_packet`	`GET /api/v1/knowledge/get_entity_packet`	Get evidence packets
`search_knowledge`	`GET /api/v1/knowledge/search_knowledge`	Search the knowledge graph and index
`resolve_entity`	`GET /api/v1/knowledge/resolve_entity`	Resolve a name to entities
`find_routes`	`GET /api/v1/knowledge/find_routes`	Find where to look something up
`get_entity_changes`	`GET /api/v1/knowledge/get_entity_changes`	Recent changes to an entity
`why_trending`	`GET /api/v1/knowledge/why_trending`	What is trending and why (key required)
`get_attention`	`GET /api/v1/knowledge/get_attention`	Attention over time for an entity
`get_source_info`	`GET /api/v1/knowledge/get_source_info`	Licence and terms of a data source
`get_upcoming_launches`	`GET /api/v1/knowledge/get_upcoming_launches`	Upcoming rocket launches
`get_galaxy_brain`	`GET /api/v1/knowledge/get_galaxy_brain`	Galaxy brain: live signals
—	`GET /api/v1/entities/{id}/packet`	One entity's evidence packet, ETag-stable

Trend intelligence

Endpoint	Returns	MCP tool	Schema
`GET /v1/why-trending`	Hourly trending entities with 3 to 5 KG-resolved news items, baseline delta and official routes	`kg_why_trending`	OpenAPI
`GET /v1/trend/categories`	The 26 categories and their Wikidata membership rules	`kg_trend_categories`	categories
`GET /v1/trend/categories/{slug}?rank_by=views\|rising`	Top 50 (or 25 rising) with share of attention, share of voice, tone and WHY	`kg_trend_categories`	category
`GET /v1/trend/share-of-voice?entities=…\|category=…`	News share per entity in a set of up to 25, shift vs previous window	`kg_share_of_voice`	compare
`GET /v1/trend/share-of-attention?entities=…\|category=…`	Wikipedia-reader share per entity, same set and windows	`kg_share_of_attention`	compare
`GET /v1/trend/tone?entities=…`	Mean GDELT tone, positive/negative scores, toned mentions, shift	`kg_entity_tone`	compare
`GET /v1/trend/history?entity=…`	Hourly (8 days) and daily (since April 2026) attention, hourly and daily mentions and tone	`kg_entity_trend_history`	history

Entities: a 4ort id, a Wikidata QID (Q26876) or a slug (taylor-swift), comma-separated, at most 25. window_hours 1 to 168, default 24. lang = all or one Wikipedia edition (en, de, fr, es, it, ja, ru, pt), never a country. Each successful call is one lookup against your allowance. Responses carry receipts, a freshness block and an ETag (send If-None-Match for a free 304).

4ort Pulse (desk gadget feed)

Endpoint	Returns
`GET /v1/pulse` · `?workspace={id}`	One JSON under 2 KB for a small e-ink screen: the world's Wikipedia attention level vs normal with a trend arrow, the 5 most-viewed entities of the latest hour, and, when your key belongs to a Marketer Alerts workspace, its latest 3 alerts

Poll once every 5 minutes (poll_s); that is 288 calls a day, inside the free key's allowance. Send If-None-Match with the last ETag: an unchanged feed answers 304 with no body. label is a display label of at most 18 characters chosen for small screens (the name, the name without its qualifier, a short alias, or its leading whole words), never a cut-off name; slug identifies the entity (/entity/{slug}). why_icon is a stable slug: news, organic_surge, organic_interest, followup. world.trend is up / down / flat from the last two hourly totals (±3%).

{"v":1,"poll_s":300,"as_of":"2026-10-24T15:50:42Z",
 "world":{"level":"normal","pct":-5,"trend":"up","arrow":"↑","hour":"2026-10-24T12:00Z"},
 "top":[{"label":"Ryo Ishibashi","slug":"ryo-ishibashi","vph":9505,"delta_pct":2505,"why_status":"organic","why_icon":"organic_surge"}, …4 more],
 "alerts":{"workspace":"4ort acceptance","items":[{"id":10,"at":"2026-10-24T16:12Z","label":"Roblox","rule":"sov_shift","test":true,"why_icon":"news"}, …]}}

Marketer Alerts workspaces

Endpoint	Does
`GET /v1/workspaces` · `POST /v1/workspaces`	List yours; create one (needs a Marketer Alerts plan or pilot)
`GET\|PATCH /v1/workspaces/{id}`	Seats, recipients, Slack, digest hour, watchlists, plan status; `alert_floors` {min_views_per_hour (default 500), min_mentions_24h (default 10)}: workspace-wide volume floors, the stricter of these and a watchlist's own applies
`POST /v1/workspaces/{id}/invites` · `POST /v1/workspaces/join`	Single-use invite codes for the three seats
`GET /v1/workspaces/entity-search?q=`	Knowledge-graph picker: watchlists take KG ids, never free text
`POST\|PATCH\|DELETE /v1/workspaces/{id}/watchlists[/{wid}]`	Up to 10 watchlists of 25 entities or one category, with thresholds and cooldowns
`GET …/watchlists/{wid}/metrics[.csv]` · `…/series`	Share of attention, share of voice and tone for the set; daily series; CSV
`POST /v1/workspaces/{id}/recipients` · `PUT /v1/workspaces/{id}/slack`	Email recipients (confirmed by link) and a Slack incoming webhook (tested before saving)
`GET /v1/workspaces/{id}/alerts[.csv]` · `POST …/test-alert`	90-day alert history with delivery status; a test alert built from live numbers (optional body `{"entity_id": …, "rule": "attention_spike\|news_surge\|sov_shift\|tone_shift"}` previews that rule's alert)

MCP

Server: https://mcp.4ort.xyz/mcp with your 4ort.xyz key as the bearer token. Its default profile lists the 8 knowledge tools; the full legacy catalogue (including the trend tools below) is at https://mcp.4ort.xyz/mcp/legacy for one release, and legacy tool names still answer on /mcp. The trend tools above declare outputSchema and return structuredContent matching it; the schemas are served at /schemas/trend-intel/{name}.json (categories, category, compare, history, share-of-attention, share-of-voice, tone, why-trending).

How numbers are computed: Methodology · clocks: Data freshness · licences: Data rights.