Developers & agents

Everything ShipReal knows about itself is available as data: the curriculum, what each module teaches, and what it costs. Three ways to read it, all the same underlying facts.

No key, no account, no signup. It is public reference data about a course, served from the edge. Nothing here is metered and nothing here writes.

There is a rate limit, and it is a brake rather than a business rule: 600 requests a minute per address, counted per edge isolate. Every response reports RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and a 429 carries Retry-After. Because the count is per isolate rather than global, treat those numbers as a pacing signal, not a guarantee.

SDK and CLI

A zero-dependency JavaScript client and a terminal tool, MIT licensed, source at github.com/mluggy/shipreal-dev.

npm install shipreal

npx shipreal search caching
npx shipreal pricing --region il
npx shipreal search --all --json | jq '.[].title'
import { ShipReal } from "shipreal";
const sr = new ShipReal();
const { data } = await sr.search("caching");
for await (const m of sr.modules()) console.log(m.title);

Install the three agent skills straight into your own agent:

npx skills add mluggy/shipreal-dev

The same repository carries the AGENTS.md working notes, the three SKILL.md documents, and an Agent Plugins manifest.

Start here

REST

Base URL: https://shipreal.dev/api/v1

# Does the course cover caching?
curl "https://shipreal.dev/api/v1/modules?q=caching"

# One module, by slug or by title fragment
curl "https://shipreal.dev/api/v1/modules/observability"

# What does it cost, in both billing regions?
curl "https://shipreal.dev/api/v1/pricing"

# Totals and subtitle languages
curl "https://shipreal.dev/api/v1/course"

Listing endpoints paginate with ?page= and ?limit= (default 20, maximum 100) and return absolute links.next / links.prev so you can walk pages without building URLs yourself.

MCP

A read-only documentation server over the streamable HTTP transport. Tools: search_curriculum, get_module, get_pricing. It also exposes the markdown documents as MCP resources.

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

Natural language

POST /ask implements the NLWeb shape: a question in, structured results out with a _meta block. Add Accept: text/event-stream for SSE, which emits start, one result per hit, then complete.

curl -X POST https://shipreal.dev/ask \
  -H 'content-type: application/json' \
  -d '{"query":"how do I make deploys safe"}'

There is no model behind this endpoint. It runs the same keyword search as the REST API, which means it will tell you plainly when nothing matches rather than inventing a module that does not exist.

Errors

Every error is RFC 9457 problem details, served as application/problem+json, so you can branch on type instead of pattern-matching prose.

{
  "type": "https://shipreal.dev/developers#errors-module-not-found",
  "title": "Module Not Found",
  "status": 404,
  "detail": "No module matches \"kubernetes\". List them at https://shipreal.dev/api/v1/modules"
}

Batch

Several reads in one round trip, for when you need six modules and do not want six requests:

curl -X POST https://shipreal.dev/api/v1/batch \
  -H 'content-type: application/json' \
  -d '{"requests":[
        {"id":"caching","path":"/modules?q=caching"},
        {"id":"obs","path":"/modules/observability"},
        {"id":"price","path":"/pricing"}
      ]}'

Up to 20 items, reads only. The envelope answers 200 whenever it is itself valid, and each item carries its own status, so check per item rather than losing a whole batch to one bad path. /batch and /exports cannot be nested inside a batch.

Versioning

The version is in the path. /api/v1 keeps answering in its current shape; anything that would break a caller ships as /api/v2 alongside it rather than as a change under your feet. Additive changes — a new field, a new endpoint — happen in place, so parse defensively and ignore fields you do not recognise.

Deprecation policy

/api/v1 is current and has no retirement date. Every response carries Deprecation: false today, so you can check a header instead of re-reading this page.

If a version is ever scheduled for retirement, it is signalled in three places, in this order:

Nothing is deprecated today, so no Sunset header is emitted: sending one for a date that does not exist would be worse than sending none.

Bulk and discovery

What there is no API for

Buying. Payment runs through a hosted checkout — Paddle as merchant of record internationally, Morning for Israeli buyers — and there is no endpoint that takes money or creates an account. An agent helping someone enrol should hand them the link and let them complete it themselves. That is a deliberate limit, not a gap waiting to be filled.

Questions, or something you need that is not here: [email protected].