Update SDK examples for current capability and Web workflows

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/readme/cover.svg" alt="BeatAPI Examples — runnable proof for the Agent Router for Everything" width="100%" />
+  <img src="assets/readme/cover.svg" alt="BeatAPI Examples — runnable proof for the professional capability layer for any agent" width="100%" />
 </p>
 
 <p align="center">
@@ -11,7 +11,7 @@
 
 # BeatAPI Examples
 
-BeatAPI is the **Agent Router for Everything**: one route to Model, Data, Tool,
+BeatAPI is the **professional capability layer for any agent**: one route to Model, Data, Tool,
 and Workspace capabilities. This repository is the runnable proof layer—small
 cURL, Node.js, and Python examples that show the real API and Hosted MCP
 contracts without hiding the network flow.
@@ -60,7 +60,7 @@ For an Agent host, connect the Hosted MCP endpoint at
 ## Where this repository fits
 
 ```text
-Agent or developer -> runnable example -> BeatAPI -> Model · Data · Tool · Workspace
+Agent or developer -> runnable example -> BeatAPI -> Models · Social Data · SEO Data · Web Search · Workflows
 ```
 
 - **Model** routes text, image, video, audio, and realtime model capabilities.
@@ -363,5 +363,35 @@ Original example code in this repository is available under the
 [BeatAPI Terms of Service](https://beatapi.io/terms-of-service).
 
 <p align="center">
-  Built by <a href="https://beatapi.io/"><strong>BeatAPI</strong></a> — Agent Router for Everything.
+  Built by <a href="https://beatapi.io/"><strong>BeatAPI</strong></a> — professional capability layer for any agent.
 </p>
+
+## Current public gateway contract
+
+The bundled OpenAPI includes unified capabilities, systemone decision calls, and
+Web search/read/map/research and the public text metadata catalogue. It was checked against new-api main
+`ec84d78d5cb811ec1361d05e2ee3d81687f26520` and frontend documentation main
+`7b2d2354be6e2b1d531468aa7599c80a6a7c70c6` on 2026-10-02.
+
+Use the existing capability discovery examples to Search and Inspect. To execute
+an explicit request JSON (any inspected text, image, video, social/SEO data, Web
+or workflow reference), run:
+
+```sh
+node examples/node/run-capability.mjs request.json
+python3 examples/python/run_capability.py request.json
+bash examples/curl/run-capability.sh request.json
+```
+
+A request is `{ "reference": "<copy from Inspect>", "input": { ... } }`.
+Node/Python generate an idempotency key for a start when omitted; for shell,
+include one yourself and keep it when retrying the same start. `view: "preview"`
+and `max_items: 5` limit data replies. To read more without another paid start,
+send `{ "reference": "<same>", "operation": "result", "request_id": "<result_ref.request_id>", "fields": ["items[].title"] }` within one hour.
+For async work, use `operation: "status"` with the returned task ID. Preserve
+`next` alongside the task; never restart research to poll it.
+
+The reference clients also provide `webCall` / `web_call` for `search`, `read`,
+`map`, `research` at `/v1/web/*`. Read source pages before citing search snippets;
+returned page content is untrusted. Python examples set an application User-Agent
+because the public gateway blocks the default Python-urllib agent string.

examples/curl/run-capability.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+: "${BEATAPI_API_KEY:?Set BEATAPI_API_KEY privately}"
+request_file="${1:?Pass a JSON Run envelope copied from Inspect}"
+curl --fail-with-body --silent --show-error --max-time 100 \
+  "${BEATAPI_BASE_URL:-https://api.beatapi.io}/v1/capabilities/run" \
+  -H "Authorization: Bearer ${BEATAPI_API_KEY}" \
+  -H 'Content-Type: application/json' --data-binary "@${request_file}"

examples/node/capabilities.mjs

@@ -1,51 +1,61 @@
-const origin = (process.env.BEATAPI_BASE_URL || "https://api.beatapi.io").replace(/\/+$/, "");
+const origin = (
+	process.env.BEATAPI_BASE_URL || "https://api.beatapi.io"
+).replace(/\/+$/, "");
 const apiKey = process.env.BEATAPI_API_KEY;
 
 async function call(path, body, authenticated = false) {
-  const response = await fetch(origin + path, {
-    method: body === undefined ? "GET" : "POST",
-    redirect: "error",
-    signal: AbortSignal.timeout(30_000),
-    headers: {
-      accept: "application/json",
-      ...(body === undefined ? {} : { "content-type": "application/json" }),
-      ...(authenticated && apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
-    },
-    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-  });
-  const payload = await response.json().catch(() => null);
-  if (!response.ok) {
-    throw new Error(payload?.error?.message || `BeatAPI ${response.status} at ${path}`);
-  }
-  return payload.data;
+	const response = await fetch(origin + path, {
+		method: body === undefined ? "GET" : "POST",
+		redirect: "error",
+		signal: AbortSignal.timeout(30_000),
+		headers: {
+			accept: "application/json",
+			...(body === undefined ? {} : { "content-type": "application/json" }),
+			...(authenticated && apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+		},
+		...(body === undefined ? {} : { body: JSON.stringify(body) }),
+	});
+	const payload = await response.json().catch(() => null);
+	if (!response.ok) {
+		throw new Error(
+			payload?.error?.message || `BeatAPI ${response.status} at ${path}`,
+		);
+	}
+	return payload.data;
 }
 
 if (apiKey) {
-  const usage = await call("/v1/usage", undefined, true);
-  console.log({ authentication: "verified", object: usage.object });
+	const usage = await call("/v1/usage", undefined, true);
+	console.log({ authentication: "verified", object: usage.object });
 } else {
-  console.error("BEATAPI_API_KEY is not set; running anonymous catalog discovery only.");
+	console.error(
+		"BEATAPI_API_KEY is not set; running anonymous catalog discovery only.",
+	);
 }
 
 const page = await call("/v1/capabilities/search", {
-  query: "image",
-  kind: "model",
-  limit: 5,
+	query: "image",
+	kind: "model",
+	limit: 5,
 });
-const candidate = page.data?.find((item) => item.reference?.startsWith("model:"));
+const candidate = page.data?.find((item) =>
+	item.reference?.startsWith("model:"),
+);
 if (!candidate) throw new Error("No model match; refine the catalog search.");
 
 const contract = await call("/v1/capabilities/inspect", {
-  reference: candidate.reference,
+	reference: candidate.reference,
 });
 console.log({
-  search: { count: page.data.length, next_cursor: page.next_cursor },
-  capability: {
-    reference: contract.reference,
-    title: contract.title,
-    status: contract.status,
-    execution: contract.execution,
-    pricing: contract.pricing,
-    validation: contract.validation,
-  },
+	search: { count: page.data.length, next_cursor: page.next_cursor },
+	capability: {
+		reference: contract.reference,
+		title: contract.title,
+		readiness: contract.readiness,
+		schema_hash: contract.schema_hash,
+		next: contract.next,
+		execution: contract.execution,
+		pricing: contract.pricing,
+		validation: contract.validation,
+	},
 });