Contract Intelligence API

HTTP API for discovering manifest schemas, browsing UI primitives, validating manifests, and getting structural guidance.

Base URL

https://public.ikary.co

All endpoints are prefixed with /api/ except the MCP endpoint at /mcp.

Authentication

None. The API is public and requires no authentication.

Quick start

Fetch the manifest schema:

curl https://public.ikary.co/api/schemas/manifest

Validate a manifest:

curl -X POST https://public.ikary.co/api/validate/manifest \
  -H "Content-Type: application/json" \
  -d '{
    "manifest": {
      "apiVersion": "ikary.co/v1alpha1",
      "kind": "Cell",
      "metadata": { "key": "test", "name": "Test", "version": "0.1.0" },
      "spec": {
        "mount": { "mountPath": "/test", "landingPage": "dashboard" },
        "pages": [{ "key": "dashboard", "type": "dashboard", "title": "Dashboard", "path": "/" }]
      }
    }
  }'

Response:

{ "valid": true, "errors": [] }

Endpoints

Schema Discovery

Method	Path	Description
GET	/api/schemas/manifest	CellManifestV1 schema
GET	/api/schemas/entity	EntityDefinition schema
GET	/api/schemas/page	PageDefinition schema
GET	/api/schemas/capability	CapabilityDefinition schema

See Schema Discovery for parameters and response examples.

UI Primitives

Method	Path	Description
GET	/api/primitives	List all 30 UI primitives
GET	/api/primitives/{key}	Get one primitive contract

See UI Primitives for the full catalog.

Example Manifests

Method	Path	Description
GET	/api/examples	List available example manifests
GET	/api/examples/{key}	Get one example manifest

See Example Manifests for available keys.

Guidance

Method	Path	Description
POST	/api/guidance/recommend	Recommend manifest structure from a business goal
POST	/api/guidance/suggest-pages	Generate pages for a set of entities
POST	/api/guidance/suggest-relations	Suggest entity relations
POST	/api/guidance/explain-errors	Turn validation errors into fix suggestions

See Guidance for request bodies and examples.

Validation

Method	Path	Description
POST	/api/validate/manifest	Validate a full CellManifestV1
POST	/api/validate/entity	Validate a single EntityDefinition
POST	/api/validate/page	Validate a single PageDefinition
POST	/api/validate/normalize	Validate and normalize a manifest

See Validation for request and response shapes.

MCP

Method	Path	Description
POST	/mcp	MCP Streamable HTTP transport (JSON-RPC 2.0)

The same capabilities are available as MCP tools for AI agents. See MCP Endpoint for connection setup.

Response format

All responses are JSON. GET endpoints return the resource directly. POST validation endpoints return { valid, errors } or { valid, manifest, errors }. POST guidance endpoints return structured recommendations.

Error responses follow a consistent shape. See Error Handling for the full reference.

Interactive documentation

Swagger UI is available at /api/docs for interactive exploration.