API Reference

Current Platform Contracts

The live API surface is split across two hosts: api.iai.one for the platform/community API and api.flow.iai.one for the Flow Engine worker surface. This page reflects the observed state on March 28, 2026.

Base URLs

Host	Role	Observed Root	Docs Guidance
`https://api.iai.one`	Platform API	200 JSON	Use this host for the currently exposed platform/community routes.
`https://api.flow.iai.one`	Flow Engine API	404 JSON at root	Treat this as a route-level worker surface, not as a browsable root endpoint.

Auth

Current Direction

api.iai.one currently exposes user registration, login, and /v1/users/me, which indicates an active user/session-oriented model on the platform API.

Future

The docs should eventually split auth by service: end-user auth for the platform API, service credentials for flow execution, and operational auth for mail/admin surfaces.

Platform API: api.iai.one

The root JSON response currently returns the following route groups:

POST/v1/users/register

POST/v1/users/login

GET/v1/users/me

GET/v1/posts

POST/v1/posts

POST/v1/verify/post

POST/v1/verify/claim

GET/v1/lessons

POST/v1/lessons/generate

POST/v1/media/upload

POST/v1/ipfs/pin

{
  "name": "IAI API — Intelligence · Artistry · International",
  "version": "1.0.0",
  "status": "ok",
  "env": "production",
  "routes": [
    "POST /v1/users/register",
    "POST /v1/users/login",
    "GET  /v1/users/me",
    "GET  /v1/posts",
    "POST /v1/posts"
  ]
}

Flow Engine API: api.flow.iai.one

api.flow.iai.one is live as a worker surface, but its root endpoint currently responds with a 404 JSON payload. That means consumers should call explicit engine routes only.

Important boundary

The Flow Engine API should not be documented by inventing a homepage-style contract. Its route-level documentation should come from the flow engine worker and the developer portal as those contracts stabilize.

{
  "ok": false,
  "error": "Not Found"
}

Developer Portal Sync

developer.iai.one is already live as a separate developer-facing surface. The documentation system now needs to keep three things aligned:

The observed route groups on api.iai.one.
The route-level Flow Engine contracts for api.flow.iai.one.
The onboarding, SDK, webhook, and node-development content published on developer.iai.one.

Current Response Shapes

The system does not yet expose a single universal response envelope across all services. The current docs should stay honest about that.

{
  "status": "ok",
  "version": "1.0.0",
  "routes": []
}

Recommended next step

Standardize response and error envelopes only after the platform API and Flow Engine API are documented as separate contracts. Right now, pretending they are the same API would make the docs less accurate, not more.