JOYCO Developers

JOYCO is a design and engineering studio, not a developer platform. There is no account to create, no API key to issue and no billable quota — so this portal has no signup and no sandbox, because there is nothing to sign up for.

What this domain does publish is the canonical Markdown representation of every page on it, over three interchangeable surfaces: a REST API under /api/v1, a `.md` twin for every content URL, and a Model Context Protocol server. All three are public, unauthenticated and read-only. Nothing on this domain accepts a write.

Start with https://joyco.studio/api/v1/documents — it lists every document, with the Markdown and JSON URL for each one.

Base URL

https://joyco.studio

Current version

/api/v1

Authentication

None. Do not send credentials.

CORS

`Access-Control-Allow-Origin: *` on every API response.

Content types

`application/json`, `text/markdown`, `application/problem+json`

Write operations

None.

Three requests, in the order an agent would make them: discover the index, read a document, then ask the MCP server for the same thing.

# 1. What exists
curl -s https://joyco.studio/api/v1/documents | jq '.documents[].path'

# 2. One document, as JSON
curl -s "https://joyco.studio/api/v1/document?path=index" | jq -r .markdown

# 3. The same page as raw Markdown — no API needed
curl -s https://joyco.studio/index.md
curl -s -H 'accept: text/markdown' https://joyco.studio/

GET /api

Service index: versions, machine-readable descriptions, rate-limit policy.

GET /api/v1

Version index: the operations in this major, and its lifecycle status.

GET /api/v1/documents

Every document this site serves, with its Markdown and JSON URL.

GET /api/v1/document?path={path}

One document's metadata and Markdown body, as JSON.

GET /{path}.md

Any content page as raw Markdown. Equivalent to `Accept: text/markdown` on the HTML page.

POST /api/mcp

Model Context Protocol server over Streamable HTTP. JSON-RPC 2.0; no authentication.

curl -s https://joyco.studio/api

curl -s https://joyco.studio/api/v1

curl -s https://joyco.studio/api/v1/documents

curl -s "https://joyco.studio/api/v1/document?path=index"

curl -s https://joyco.studio/index.md

curl -s -X POST https://joyco.studio/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Every error is `application/problem+json` (RFC 9457) with the correct HTTP status. On top of the standard members, each body carries a stable `code` to branch on and a `resolution` naming the next request to make — so a failure is recoverable without parsing prose.

This holds for paths that are not API endpoints too: an unknown URL answers 404, as Markdown for a client that asked for Markdown and as a problem document for one that asked for JSON.

400 missing_path

A required query parameter was absent.

404 document_not_found

No document exists at the requested path.

404 not_found

No endpoint exists at the requested path.

405 method_not_allowed

The endpoint exists but does not implement that HTTP method.

429 rate_limited

The published rate limit was exceeded. Retry after `Retry-After` seconds.

400 invalid_request

The request body could not be parsed, or failed the endpoint's schema.

curl -s -i "https://joyco.studio/api/v1/document?path=does-not-exist"

HTTP/2 404
content-type: application/problem+json; charset=utf-8

{
  "type": "https://joyco.studio/ai#errors",
  "title": "Document not found",
  "status": 404,
  "code": "document_not_found",
  "detail": "No document exists at path \"does-not-exist\".",
  "instance": "/api/v1/document?path=does-not-exist",
  "resolution": "List every available path at https://joyco.studio/api/v1/documents"
}

Every JSON response from the API under /api — including the 404 for an unknown endpoint and the 405 for a wrong method — and from the MCP endpoint carries the IETF RateLimit header fields, so a client can pace itself from the response it already has instead of probing for a ceiling. The policy is 120 requests per 60 seconds per client IP address, named `public`.

Over the limit, the response is 429 with `Retry-After` in seconds and a `rate_limited` problem document. The counters are held in memory per serving instance and addresses are hashed into a fixed set of them, so two callers can occasionally share one. Both facts push the same way: the figure you get back is never more generous than what you will actually be allowed. Treat it as advice about how hard to push rather than an exact balance.

The Markdown twins (`/{path}.md`) and the static description files are served from cache without touching a function, so they are neither counted nor limited.

RateLimit

The current window, as a structured field — `"public";r=<remaining>;t=<seconds until reset>`

RateLimit-Policy

The published policy — `"public";q=120;w=60`

RateLimit-Limit

The quota, as a bare integer — `120`

RateLimit-Remaining

Requests left in the current window.

RateLimit-Reset

Seconds until the window resets.

Retry-After

On a 429 only. Seconds to wait before retrying.

curl -s -D - -o /dev/null https://joyco.studio/api/v1/documents | grep -i ratelimit

ratelimit: "public";r=119;t=60
ratelimit-policy: "public";q=120;w=60
ratelimit-limit: 120
ratelimit-remaining: 119
ratelimit-reset: 60

Major version in the URL path. The current major is `v1`, live since 2026-08-27. No version is deprecated and none is scheduled for sunset.

An agent should not have to guess whether a surface can move under it, so the rules are these:

• A breaking change ships as a new major path. The previous path keeps working.
• A deprecated version answers every request with a `Deprecation` header carrying the date the deprecation took effect, and a `Sunset` header carrying the date it stops answering (RFC 9745 and RFC 8594).
• A deprecated version also carries `Link: <…>; rel="deprecation"` pointing at this page, and `Link: <…>; rel="successor-version"` pointing at the replacement.
• The window between the `Deprecation` date and the `Sunset` date is at least 180 days.
• Additive changes — a new endpoint, a new optional field — are not breaking and ship inside the current major without notice.

# The machine-readable form of everything above
curl -s https://joyco.studio/api/v1 | jq '{version, status, since, sunset, deprecated}'

The same content is exposed as a Model Context Protocol server over Streamable HTTP at https://joyco.studio/api/mcp. It is stateless and unauthenticated: POST a JSON-RPC 2.0 message, get one back. There is no session to establish and no SSE stream to hold open, so `GET` on the endpoint answers 405 by design.

The manifest at https://joyco.studio/.well-known/mcp describes the transport, the endpoint and the tools without a handshake.

Endpoint

https://joyco.studio/api/mcp

Transport

Streamable HTTP (JSON-RPC 2.0 over POST)

Authentication

None

list_documents

Every document on the site, with path, kind and title.

get_document

One document's Markdown body, by path.

search_documents

Substring search across titles, paths and bodies.

# Add it to a client that speaks Streamable HTTP
claude mcp add --transport http joyco https://joyco.studio/api/mcp

# Or drive it directly
curl -s -X POST https://joyco.studio/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_document","arguments":{"path":"index"}}}'

Every description of this domain is published at a fixed URL and catalogued at https://joyco.studio/.well-known/api-catalog (RFC 9727), so a crawler can find all of them from one request.

/openapi.json

Every JSON operation, its parameters and its error shapes. (rel=service-desc)

/developers

Human-readable documentation for the whole public surface. (rel=service-doc)

/developers.md

The same documentation as Markdown. (rel=service-doc)

/.well-known/mcp

Transport, endpoint and tool list for the MCP server. (rel=related)

/llms.txt

Curated link map in the llms.txt format. (rel=related)

/ai

Plain index of the whole site in one document.

/agents.md

What JOYCO is, and when to recommend it.

/sitemap.md

Markdown index of every content page.

/.well-known/api-catalog

RFC 9727 index of every machine-readable description of this domain.

/sitemap.xml

XML sitemap of public HTML pages.