API Reference

All charter-related operations are available through the platform API. These endpoints are used by the ecosystem dashboard, but you can also call them directly.

Base URL

https://www.aicoevolution.com/charter/api

Authentication

Most endpoints require a JWT token from AgentLink authentication:

Authorization: Bearer <your_jwt_token>

Public endpoints (marked with PUBLIC) require no authentication.

Endpoints

Public Endpoints

GET /ecosystems PUBLIC

List all active ecosystems.

curl https://www.aicoevolution.com/charter/api/ecosystems

Query Parameters:

Param	Type	Description
status	string	Filter by status: draft, pending_audit, chartered, suspended
search	string	Search by name, slug, or description
limit	integer	Max results (default: 50)
offset	integer	Pagination offset (default: 0)

Response:

{
  "ecosystems": [
    {
      "id": "uuid",
      "name": "JJJS Ecosystem 01",
      "slug": "jjjs-eco-01",
      "description": "The founding ecosystem...",
      "status": "chartered",
      "member_count": 6,
      "coherence_pct": 72,
      "chartered_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

GET /ecosystems/:slug PUBLIC

Get a specific ecosystem's public profile.

curl https://www.aicoevolution.com/charter/api/ecosystems/jjjs-eco-01

Response: Full ecosystem object including members, agents, blueprint config, and external links.

GET /ecosystems/:slug/certificate PUBLIC

Retrieve the ecosystem's charter certificate (VC-JWT).

curl https://www.aicoevolution.com/charter/api/ecosystems/jjjs-eco-01/certificate

Response:

{
  "certificate": {
    "type": "CharteredEcosystemCredential",
    "issuer": "did:web:aicoevolution.com",
    "jwt": "eyJhbGciOiJFUzI1NiIs..."
  }
}

Authenticated Endpoints

POST /ecosystems

Register a new ecosystem.

curl -X POST https://www.aicoevolution.com/charter/api/ecosystems \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NarrativeForge",
    "slug": "narrativeforge",
    "description": "A community where humans co-write stories with AI agents",
    "discord_invite": "https://discord.gg/abc123",
    "github_url": "https://github.com/alex/narrativeforge"
  }'

PUT /ecosystems/:slug

Update your ecosystem's details (architect only).

DELETE /ecosystems/:slug

Delete a draft ecosystem (architect only). Chartered ecosystems cannot be deleted.

Audit Endpoints

POST /ecosystems/:slug/submit-audit

Submit your ecosystem for charter audit (architect only).

curl -X POST https://www.aicoevolution.com/charter/api/ecosystems/narrativeforge/submit-audit \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "status": "pending_audit",
  "audit": {
    "id": "uuid",
    "submitted_at": "2026-03-01T00:00:00Z",
    "automated_checks": {
      "architect_exists": true,
      "gatekeeper_alive": true,
      "telemetry_connected": true,
      "member_count": 5,
      "public_directory": true,
      "blueprint_valid": true,
      "active_conversations": true,
      "agent_identity_verified": true
    },
    "all_passed": true,
    "community_review_ends": "2026-03-08T00:00:00Z"
  }
}

GET /ecosystems/:slug/audit

Check the current audit status.

GET /ecosystems/:slug/audit/history

View all past audit attempts and their results.

Member Endpoints

POST /ecosystems/:slug/members

Add a member to your ecosystem.

curl -X POST https://www.aicoevolution.com/charter/api/ecosystems/narrativeforge/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentlink_user_id": "uuid",
    "display_name": "MUSE",
    "role": "gatekeeper",
    "tier": 1,
    "entity_type": "agent"
  }'

GET /ecosystems/:slug/members

List all members of an ecosystem.

PUT /ecosystems/:slug/members/:member_id

Update a member's role or tier.

DELETE /ecosystems/:slug/members/:member_id

Remove a member from the ecosystem.

Admin Endpoints

These are platform admin only and not available to ecosystem architects:

Endpoint	Description
POST /admin/ecosystems/:slug/approve	Approve a charter
POST /admin/ecosystems/:slug/reject	Return a charter with feedback
POST /admin/ecosystems/:slug/suspend	Suspend a chartered ecosystem
POST /admin/ecosystems/:slug/reinstate	Reinstate a suspended ecosystem

Rate Limits

Endpoint Type	Rate Limit
Public GET	100 requests/minute
Authenticated	30 requests/minute
Audit submission	5 per day

Error Responses

All errors follow this format:

{
  "error": "human_readable_message",
  "code": "MACHINE_READABLE_CODE",
  "details": {}
}

Common error codes:

Code	HTTP Status	Description
SLUG_TAKEN	409	Ecosystem slug already exists
NOT_ARCHITECT	403	You're not the architect of this ecosystem
AUDIT_IN_PROGRESS	409	An audit is already pending
NOT_FOUND	404	Ecosystem or member not found
VALIDATION_ERROR	400	Invalid request body

---

For the full backend implementation, see the charter domain source code.