AI Transformation.io

Agent protocol v1

For agents & agent builders

ai-transformation.io is agent-friendly by design. Humans read editorial pages; agents use versioned JSON APIs with the same curated signals. Implementation status: wave7_v1 (live).

Quick start (copy into your agent)

Primary agent entry: https://ai-transformation.io/api/agent — holistic text intro (not a raw endpoint list). JSON details: capabilities.

You can interact with https://ai-transformation.io without browsing HTML.

Start at GET https://ai-transformation.io/api/agent — holistic site intro and API orientation (text).
Set a stable X-Agent-Client-Id header (e.g. "your-agent/1.0") on content reads — 3/day anonymous, 10/day after authorize.

1. Call GET https://ai-transformation.io/api/v1/capabilities — quotas, endpoints, error codes, and auth rules.
2. Call GET https://ai-transformation.io/api/v1/content?site=io — article index with api_url per entry (no read quota).
3. Call GET https://ai-transformation.io/api/v1/curated?site=io — what editors highlight now.
4. Call GET https://ai-transformation.io/api/v1/content/{slug}?site=io — full article body (counts as a read).
5. To submit on behalf of a human (inquiries (question box)):
   POST https://ai-transformation.io/api/v1/agent/authorize (human completes one email confirm),
   then POST https://ai-transformation.io/api/v1/contributions with Authorization: Bearer <token>.

Errors return JSON: { ok: false, error: "machine_code", message?: "..." }.
Human-readable protocol: https://ai-transformation.io/for-agents

What you can do today

  • Capabilities — GET /api/v1/capabilities lists endpoints, quotas, error codes, client_id guidance, and a quick_start array. Always call this first.
  • Content index — GET /api/v1/content?site=io lists all slugs (does not consume read quota).
  • Curated feed — GET /api/v1/curated?site=io returns editor highlights from the home page.
  • Article body — GET /api/v1/content/{slug}?site=io with optional X-Agent-Client-Id (3 reads/day anonymous, 10/day after authorize).
  • Write token — POST /api/v1/agent/authorize → human email confirm → 180-day Bearer token shared across .io and .org.
  • Contributions — POST /api/v1/contributions with Bearer token; scope write:inquiry on .io.
  • Community write/action API parity — Phase 1 community endpoints are available at /api/v1/community/* with Bearer/session parity, and community objects are created via /api/v1/objects / /api/v1/objects/submit. .io has no community UI, but the shared Agentic Access API supports the same contracts used by .org.
  • Phase 2 opportunity types are active — question, mentorship_request, project_request, collaboration_offer, and apprenticeship_opportunity now support real fields, create/submit/list/detail, and type-appropriate actions through the shared API.
  • Experimental matching — call POST /api/v1/community/match for ranked candidates + reasons, and POST /api/v1/community/match/feedback for thumbs feedback persistence (same behavior as session-based .org UI).
  • Changelog — GET /api/v1/agent/changelog returns versioned entries when the API changes.

Matching remains clearly labeled as experimental while the rule-based scorer and feedback loop are calibrated.

Client identity

Send a stable X-Agent-Client-Id header on content reads — e.g. your-agent-name/1.0 or a UUID you reuse per deployment (1–120 characters). This tracks anonymous read quota. After authorize, reads tied to the verified email get the higher quota.

Error responses

Failed requests return JSON: { ok: false, error: "machine_code", message?: "..." }. Common codes: not_found (404), read_quota_exceeded (429), missing_token / invalid_token (401), validation_error (400). Content reads include X-RateLimit-* headers.

Library articles and insight cards carry discreet Continue with an external agent links beside Open in Ask. Each link opens ChatGPT or Claude with a pre-filled prompt that already contains the page URL and a suggested question, so a reader can hand the page to their own agent in one click. The detail page also embeds a machine-readable hint as a <script type="application/json" data-agent-hint="external-agent"> block (canonical url + suggested prompts) for agents that parse the page.

Build the same links yourself: q is a URL-encoded prompt that includes the page URL.

Example prompts for Claude or similar

  • “Call https://ai-transformation.io/api/v1/capabilities then https://ai-transformation.io/api/v1/content?site=io and summarize available topics.”
  • “Fetch the governance framework slug from the content index and list three decisions for a CIO.”
  • “After authorize, submit my insight about pilot purgatory as an inquiry on .io.”