API reference — ceiba.to

Endpoints (every ceiba must serve)

Endpoint	Status	Purpose
GET/.well-known/ceiba.json	required	Self-descriptor manifest. Validates against ceiba.schema.json.
GET/health	required	Returns `{"ok": true, "ceiba": "name", "ts": "..."}`.
GET/v1/<type>s	required	List entities of the given type. Pagination via `?limit` + `?offset`.
GET/v1/<type>s/<id>	required	Fetch one entity by id.
GET/v1/stats	required	Aggregate counters: `{"entities": N, "members": N, "events": N}`.
GET/llms.txt	L1	Plain-text site index for LLM consumers. Short.
POST/v1/<type>s/<id>/claim	L2	Claim a profile. Trigger the configured verification method.
POST/v1/<type>s/<id>/edit	L2	Propose an edit. Logged in `edit_history` with source attribution.
GET/mcp	L3	Model Context Protocol server. Discoverable via `Accept: application/json`.
GET/v1/events/sync	federation (opt-in)	Push endpoint for receiving events from federated peers. Scope-gated.

Manifest schema (top-level fields)

Authoritative source: /ceiba.schema.json (Draft 2020-12). Below is the human-friendly summary.

id string (uri) required

Canonical URL of the ceiba (trailing slash). Matches url in practice.

name string (kebab-case) required

Unique slug across the registry. Must not collide with existing entries.

displayName string required

Title-case human name.

protocol_version string (semver) required

Currently "0.5". Additive over "0.4" — both validate.

roles_supported array<enum>

Subset of ["operator", "contributor", "entity-owner"]. v0.5 addition.

type enum required

One of community, infrastructure, data-project.

identity object required

entity_types[], claim_enabled, verification_method, auth_methods[], profile_statuses[].

data object

source_attribution, edit_history, open_editing, license (default CC BY 4.0).

api object

base_url, health, llms_txt, mcp_server, schema_org.

federation object

sync_pull, sync_push, discovery (static-registry | peer-discovery).

interconnections array<object>

Federation links to other ceibas, with scopes and api_key_required (v0.5).

linked_entities array<object>

v0.5 — references to federated self-sovereign entities with scopes/TTL.

api_keys_emit object

v0.5 — declares whether this ceiba issues scoped API keys for third parties.

karma object

enabled, transferable (default false), split (default {contributors: 0.80, commons_fund: 0.20}).

payment_rails array<enum>

16 values in v0.5: stablecoin_usdc, x402, fiat_invoice, lightning, mercadopago, stripe, wise, spei, oxxo, pix, sepa, ach, bank_transfer, manual, …

compliance_level integer (0-3) required

Self-declared. See the compliance ladder below.

Curl examples (against a live ceiba)

Self-describe

curl -s https://lacartelera.app/.well-known/ceiba.json | jq '.protocol_version, .compliance_level'
# → "0.4"
# → 3

List entities of a type

curl -s "https://lacartelera.app/v1/comedians?limit=3"
# → array of comedian objects

Fetch a single entity

curl -s https://lacartelera.app/v1/comedians/<comedian-id>

Stats

curl -s https://lacartelera.app/v1/stats
# → {"entities": 427, "members": 227, "events": 66}

MCP discovery (L3)

curl -s https://lacartelera.app/mcp -H "Accept: application/json"

Validate any manifest against the schema

curl -sf https://ceiba.to/ceiba.schema.json -o /tmp/schema.json
curl -sf https://<any-ceiba>/.well-known/ceiba.json -o /tmp/manifest.json
python -c "import json, jsonschema; jsonschema.validate(json.load(open('/tmp/manifest.json')), json.load(open('/tmp/schema.json'))); print('VALID')"

Conventions

Entity-type paths are plural. If identity.entity_types is ["comedian"], the CRUD lives at /v1/comedians.
Slugs are kebab-case. The name field follows this.
Dates are ISO-8601, UTC or explicit timezone.
Pagination: ?limit + ?offset, or cursor-based via ?after=<id>.
License default: CC BY 4.0 for the public graph. Each ceiba can override.
Privacy boundary: if the data would exist without your product, it belongs to the commons. Spec §5.

API reference.