API reference

Developer API

Foundation Beta reference for API keys, Inkwell billing, rate limits, and the first 121 v1 endpoints.

Early access

Authentication

Create API keys from /app/developer. Keys have a name, a read_only or read_write scope, and a one-time plaintext reveal. After creation, the console shows only the last four characters.

curl https://www.121collaborative.ai/api/v1/me \
  -H "Authorization: Bearer 121_live_your_api_key"

Rate limits

Tier	Requests/min	Requests/day
Free	60	1000
PWYC	120	5000
Standard	600	50000
Patron	1200	250000

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Billing

API usage counts against the same Inkwell allowance ledger as hosted app usage. Spend events use raw_cost x 1.80 x 1.15 and round up to exact allowance units. If allowance is unavailable, endpoints return 402 Payment Required with a top-up URL.

Endpoints

Method	Path	Scope	Description
`GET`	`/api/v1/me`	`read_only`	Return the authenticated peer profile, tier, allowance remaining, and subscription status.
`GET`	`/api/v1/usage`	`read_only`	Return the last 30 days of API usage, grouped by UTC day.
`GET`	`/api/v1/tiers`	`public`	Return public Inkwell tier pricing and the raw-cost pricing formula.
`POST`	`/api/v1/inkwell/spend`	`read_write`	Record an Inkwell spend event and decrement the peer's daily allowance.
`GET`	`/api/v1/research/papers`	`read_only`	List the 121 research bundle papers exposed through the research MCP surface.
`GET`	`/api/v1/declaration`	`read_only`	Return the current public Declaration text, status, version, and canonical URL.

Spend example

curl https://www.121collaborative.ai/api/v1/inkwell/spend \
  -H "Authorization: Bearer 121_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"provider":"external-integration","raw_cost_cents":12,"metadata":{"job_id":"example"}}'

Errors

401
{ "error": "Invalid API key." }

402
{
  "error": "insufficient_allowance",
  "current_allowance_remaining": 0,
  "top_up_url": "https://www.121collaborative.ai/app/usage"
}

429
{ "error": "rate_limited", "reason": "minute" }

Coming soon

Webhooks are coming soon. SDKs are coming soon and will link to GitHub when ready.