# aicoolies developer portal

This is the aicoolies developer portal: API documentation, OpenAPI, MCP, authentication rules, and a live sandbox against production catalog data. Use it to wire an agent or a script without inventing a scrape.

## Authentication and scopes

Public catalog reads are unauthenticated with CORS *. MCP community writes use GitHub-bound personal access tokens from /settings/tokens: correction:write covers submit_correction and report_price_change; stack:write covers sync_stack; room:write covers reply_to_room; run:write covers submit_run; and vote:write covers upvote_tool. New tokens default only to correction:write and stack:write. GitHub OAuth 2.0 remains the human sign-in flow and requests only read:user and user:email. aicoolies is not an OAuth authorization server; the full split is published as RFC 9728 metadata at /.well-known/oauth-protected-resource.

## Quickstart

Fetch https://aicoolies.com/api/agents/meta to see collection counts and an ETag. If the ETag changed, pull https://aicoolies.com/api/agents/context or the CC-BY JSON files under /data. Prefer If-None-Match. For a typed contract, load https://aicoolies.com/openapi.json.

## Sandbox

The read examples below use the live catalog and need no key. MCP writes use a revocable personal access token and are never shown as sandbox examples because they create real moderated contributions.

## Contract guarantees

The current major version is 1 and every response carries an API-Version header. Version-pinned paths live under /api/v1; the unversioned paths are permanent aliases of the current major. A breaking change ships under a new prefix, and the outgoing one signals Deprecation, Sunset, and a deprecation Link for at least 180 days first. Failures are RFC 9457 problem documents served as application/problem+json with a machine-readable code, and every response carries advisory RateLimit headers so a client can pace itself instead of guessing.

## Endpoints

- OpenAPI: https://aicoolies.com/openapi.json
- MCP: https://aicoolies.com/mcp
- Manifest: https://aicoolies.com/.well-known/mcp.json
- Agent context: https://aicoolies.com/api/agents/context
- Agent meta: https://aicoolies.com/api/agents/meta
- Version-pinned aliases: https://aicoolies.com/api/v1/agents/context, https://aicoolies.com/api/v1/agents/meta
- Tools dataset: https://aicoolies.com/data/tools.json
- MCP discovery: https://aicoolies.com/.well-known/mcp, https://aicoolies.com/.well-known/mcp/server-card.json
- OAuth protected resource metadata: https://aicoolies.com/.well-known/oauth-protected-resource
- llms.txt: https://aicoolies.com/llms.txt

## Contract

- Versioning: /api/v1 is the pinned major; unversioned paths are permanent aliases. Every response carries API-Version.
- Errors: RFC 9457 problem documents (application/problem+json) with a machine-readable code.
- Rate limits: advisory RateLimit and RateLimit-Policy headers; 429 carries Retry-After.
- Authorization: catalog reads are anonymous; MCP writes use scoped personal access tokens from /settings/tokens. aicoolies is not an OAuth authorization server and issues no OAuth access tokens; https://aicoolies.com/.well-known/oauth-authorization-server answers 404 on purpose. Permission model: https://aicoolies.com/.well-known/oauth-protected-resource.
- CLI: npm package https://www.npmjs.com/package/aicoolies — npx aicoolies meta | context | search | tool | resources | openapi