World

Package world is a live news feed filtered to what your project cares about.

Quickstart

export HANZO_API_KEY=hk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/world, operation get_world:

hanzo world get

import { Configuration, WorldApi } from 'hanzoai';

const api = new WorldApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getWorld();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import WorldApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = WorldApi(client).get_world()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.WorldAPI.GetWorld(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, world_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = world_api::get_world(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.WorldApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new WorldApi(client).getWorld();

curl https://api.hanzo.ai/v1/world \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "world",
         "arguments": {
           "op": "get_world",
           "input": {}
         }
       }
     }'

Answers 200 with object — ok.

world

GET /v1/world/limits

Echoes a World plan's rate limits, alert quota and model-API grant, read straight from the live @hanzo/plans catalog, so agents and dashboards configure themselves against the catalog instead of hardcoding tier numbers.

An empty or unknown plan resolves world-free, and a catalog failure serves that same free floor rather than erroring — so this always answers 200, and it can only ever under-grant. It reports the contract; it does not enforce it.

GET /v1/world/news

Returns the caller's merged world-news feed: every source their project's pipeline names — GDELT once per keyword, plus each allowlisted RSS or Atom feed — fetched concurrently, narrowed by the pipeline's keyword/region/source filters, deduplicated by link and sorted freshest first, capped at 50 items.

A project with no stored pipeline gets a sensible default set of world feeds rather than an empty answer. A source that fails or times out is SKIPPED: the feed degrades to honest partial results and never 5xxs because one outlet was down. Reading also publishes the result to the /v1/world/stream subscribers of the same (org, project), so a dashboard's own refresh updates every open tab.

GET /v1/world/pipeline

Returns the caller project's news pipeline: which feeds it reads and how the merged result is filtered. A project that has never written one is answered with the built-in world feeds and default: true, so a fresh project sees the same feed /v1/world/news would actually serve rather than an empty configuration.

PUT /v1/world/pipeline

Replaces the caller project's news pipeline and returns what was stored. It is a WHOLE replacement, not a patch: a field the request leaves out is stored empty, so sending only feeds clears the filters.

Every feed URL is validated HERE, at the write boundary — http(s) only, and the host must be on the server's allowlist — so a stored pipeline can never name a host the fetcher would later refuse, and the allowlist is one decision in one place rather than a check at each fetch.

Request body — application/json (required)

GET /v1/world/stream

Live news refreshes for the caller's org and project, as Server-Sent Events.

Holds the connection open as text/event-stream and pushes a news event — the same {items:[…]} body GET /v1/world/news answers — each time the caller's (org, project) feed refreshes, with a : ping heartbeat comment every 25s. Delivery is best-effort: a slow consumer is dropped on buffer overrun and reconnects, re-fetching GET /v1/world/news, which stays the source of truth. Requires a validated principal; 403 without one.

GET /v1/world

Answers GET /v1/world — the product's front door, naming every wire this surface answers on.

It exists because two of those wires are INVISIBLE to the generated document. /v1/world/mcp and /v1/world/zap are carved off the cloud catch-all by the ingress and answered by world-gw, so the cloud router never serves them — and openapi.Describe renders prose only for a route the router actually serves, which is the very property that keeps the document from being able to claim an operation nothing answers. Both addresses are real and public, so without this op the only way to learn they exist is to read the ingress config. This is where that fact lives, in the product's own surface.

Public on purpose: discovery precedes credentials. It reports addresses and protocols only — never feed data, and never the caller's plan, which GET /v1/world/limits owns — so there is nothing here to leak.

All Hanzo APIs · Interactive reference