# RoutineHub v1 API

> Official HTTP API for RoutineHub. Publish and retrieve iOS Shortcuts, and publish Claude Prompts, Skills, and Plugins to the registry. Authentication is a RoutineHub API key carried as a path segment.

The machine-readable contract is the OpenAPI 3.1 spec — fetch it and use it directly.

## Specs
- [OpenAPI 3.1 spec](https://routinehub.co/v1/openapi.json): full machine-readable contract for every v1 endpoint.

## Docs
- [Developer docs hub](https://routinehub.co/docs/): index of everything below.
- [API reference (Redoc)](https://routinehub.co/docs/api/): human-readable reference.
- [Swagger UI](https://routinehub.co/docs/swagger/): interactive explorer.
- [Publishing CLI](https://routinehub.co/docs/cli/): publish and price an item from a terminal.

## MCP server (agents: prefer this)
- Endpoint: https://routinehub.co/api/v1/<api_key>/mcp (streamable HTTP JSON-RPC, stateless).
- Connect from Claude Code: `claude mcp add --transport http routinehub https://routinehub.co/api/v1/<api_key>/mcp`
- Tools cover the registry end to end: search, fetch items and versions, fork, publish prompts/versions, set price and license, list your items, and propose/review updates.
- Human walkthrough: https://routinehub.co/connect-claude/

## Registry (prompts / skills / plugins)
- Full CRUD over REST: /api/v1/<api_key>/registry/skills, .../registry/prompts, .../registry/plugins (see the OpenAPI spec for shapes).
- Browse pages for context: https://routinehub.co/prompts/ https://routinehub.co/skills/ https://routinehub.co/plugins/

## Install a skill (one command)
A published skill's files are served as plain HTTP GETs — no key needed for free skills. To install one, create its folder and pull each file:
```
SKILL_DIR=~/.claude/skills/<slug>
mkdir -p "$SKILL_DIR"
curl -sL -o "$SKILL_DIR/SKILL.md" "https://routinehub.co/skill/<slug>/file/SKILL.md/download"
# ...repeat one curl per file in the bundle...
```
- Per-file download: https://routinehub.co/skill/<slug>/file/<path>/download
- Whole bundle as a zip: https://routinehub.co/skill/download/<version_id>/?format=zip
- Each skill's install page prints the exact per-file curl list: https://routinehub.co/skill/<slug>/download
- Agents with a key can skip the curls: call the MCP `install_item` tool, which returns the complete file set (with suggested install paths) in one call.

## Publish a skill (one POST)
Publish a SKILL.md straight from a phone, the Shortcuts app, or any AI agent — Claude (CLI/Desktop/web), Codex, Gemini, or plain curl — one form POST, no multipart needed. Get your key at https://routinehub.co/settings-api

```
curl -X POST "https://routinehub.co/api/v1/<api_key>/registry/skills" \
  --data-urlencode "name=My Skill" \
  --data-urlencode "brief=One line about what it does" \
  --data-urlencode "version=1.0" \
  --data-urlencode "skill_md@SKILL.md"
```
- `skill_md` is the SKILL.md text pasted as a form field; it must start with YAML frontmatter carrying `name` and `description`.
- Multi-file bundles: send repeated multipart `files` parts instead (each part's filename = its bundle-relative path); exactly one root SKILL.md. Limits: 25 files, 256 KB/file, 2 MB total, text types only.
- Success = HTTP 201 with the live listing URL. 400 invalid, 409 if that exact SKILL.md is already published, 429 past the daily cap.
- New releases: POST the same shape to .../registry/skills/<slug>/versions with the new `version`.

### Sell it or give it away
- Free (community) is the default — just omit `price_usd`.
- To sell, add `price_usd` (and `payout` = `stripe` or `crypto_usdc_base` if both rails are onboarded). Prices are exact decimal strings: minimum $0.50, at most 2 decimal places — `"4.99"` is valid, `"4.999"` is rejected with 400. Amounts are never handled as floats. Send `"0"` to make a paid skill free again.
- Selling requires one-time seller onboarding (Stripe or crypto) on your account.

## Notes
- Payment/subscription webhooks (Stripe) exist and are documented under the `Webhooks` tag in the OpenAPI spec, but they are INBOUND-ONLY: called by Stripe and authenticated by the Stripe signature, never by an API key. Do not call them as an agent.
- Base URL: https://routinehub.co/api/v1
- Auth: pass your API key as a path segment, e.g. /api/v1/<api_key>/shortcuts
- Responses use a {"result":"success"|"error"} envelope.
- Legacy shortcut endpoints may return HTTP 200 even on error — check the "result" field.