aicoolies logo

> aicoolies developer resources

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 endpoints are unauthenticated GET requests with CORS *. Do not send an API key: every operation in the OpenAPI document declares an empty security requirement. GitHub OAuth 2.0 exists only for human visitors who sign in to manage a /dev profile, comments, or personal stacks, and it requests two identity scopes — read:user and user:email — and nothing else. That session is a first-party cookie scoped to the one account it belongs to; aicoolies issues no third-party tokens, so those routes stay out of the public function-calling surface. The same statement 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 sandbox is the live catalog. There is no separate staging key. Call the production URLs below from curl, the aicoolies CLI, or any MCP client pointed at https://aicoolies.com/mcp. Responses are cacheable for an hour.

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.

aicoolies public endpoints

Discovery URLs (.well-known)

RFC 8615 reserves the /.well-known/ prefix for machine-readable metadata, which is why these paths look like file names rather than pages. MCP server discovery is still being standardised — competing proposals put the document at /.well-known/mcp.json, /.well-known/mcp, and /.well-known/mcp/server-card.json, so aicoolies publishes all three and keeps them consistent.

Permissions and OAuth

Every endpoint in the OpenAPI document declares security: []: the public catalog is readable with no credential, no API key, and no token. The only authorization aicoolies performs is a human GitHub sign-in for developer profiles, comments, and personal stacks. That flow is an OAuth 2.0 authorization code exchange with GitHub and requests exactly two identity scopes — read:user, user:email — never repository, organization, or write access. The resulting session is a first-party cookie scoped to that one account; aicoolies issues no tokens to third-party clients, so no account route appears in the public contract. The machine-readable version of this paragraph is at /.well-known/oauth-protected-resource.

aicoolies is not an OAuth authorization server, by choice. There is no token to request and no scope to negotiate, and /.well-known/oauth-authorization-server answers 404 with that explanation rather than a fabricated document. Everything an agent needs — the catalog, the datasets, the MCP tools — is readable without any credential, so delegated access would add a token-issuing surface that nothing currently needs. If you are building something that genuinely needs to act for a signed-in aicoolies user, such as reading or updating their stack on their behalf, say so on the contact page. That demand is what would justify building it, starting with read-only scopes.

Versioning and deprecation

The current major version is 1. Every API response carries API-Version: 1. Version-pinned paths live under /api/v1 — for example /api/v1/agents/context — and the unversioned paths are permanent aliases of the current major, running the same handler.

A breaking change ships under a new prefix. The outgoing major then answers with Deprecation (RFC 9745), Sunset (RFC 8594), and a Link; rel="deprecation" header pointing here, for at least 180 days before removal. Nothing is deprecated today. The MCP endpoint negotiates separately: it speaks 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and echoes back the version the client asked for when it is on that list.

Rate limits

Limits are advisory and generous — a full catalog crawl should never trip them. Responses carry RateLimit-Policy, RateLimit, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; a 429 adds Retry-After. Values seen through a shared cache can be a few seconds stale.

  • agent-api: 120 requests / 60s
  • dataset: 60 requests / 60s
  • mcp: 120 requests / 60s

Error model

Every 4xx and 5xx from the public API is an RFC 9457 problem document served as application/problem+json. Branch on code — the closed set below — and show detail to humans. The error field mirrors detail for clients written before this model. The MCP endpoint is the one exception: it answers in JSON-RPC 2.0 error objects, as that protocol requires.

invalid_parameter — HTTP 400
Invalid request parameter
unknown_category — HTTP 400
Unknown category slug
malformed_request — HTTP 400
Malformed request body
unsupported_protocol_version — HTTP 400
Unsupported MCP protocol version
not_found — HTTP 404
Resource not found
method_not_allowed — HTTP 405
Method not allowed
rate_limited — HTTP 429
Rate limit exceeded
internal_error — HTTP 500
Internal server error
database_unavailable — HTTP 503
Database unavailable

aicoolies CLI

The aicoolies CLI wraps the same public URLs, so a script or an agent can read the catalog without writing an HTTP client. It ships on npm as aicoolies with zero dependencies, so npx pulls a single file. It needs no API key and no configuration; point it at another origin with AICOOLIES_URL.

  • npx aicoolies meta

    Collection counts and freshness timestamps.

  • npx aicoolies context --include tools --compact

    Catalog index, optionally filtered and slug-only.

  • npx aicoolies search cursor

    Search the catalog by name or slug.

  • npx aicoolies tool cursor

    One tool record from the CC-BY dataset.

  • npx aicoolies resources

    Print every official developer resource URL.

  • npx aicoolies openapi

    Fetch the OpenAPI 3.1 document.

Live sandbox

These commands hit production. Copy them into a terminal. There is no separate staging key.

Freshness probe

curl -sS https://aicoolies.com/api/agents/meta

Compact tool slugs

curl -sS 'https://aicoolies.com/api/agents/context?include=tools&compact=true'

Version-pinned call

curl -sS https://aicoolies.com/api/v1/agents/meta -D -

OpenAPI

curl -sS https://aicoolies.com/openapi.json

MCP initialize

curl -sS https://aicoolies.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl"}}}'

Markdown rendition of any page

curl -sS https://aicoolies.com/tools/cursor -H 'Accept: text/markdown'