API reference.

Base URL: https://recipes.wisechef.ai/api

Auth: x-api-key: rec_xx... header. All install and write endpoints require a valid API key. Read-only endpoints (search, skill detail, carousel) are public.

Rate limit: 60 req/min per key (burst 10). Exceeding returns 429 with a Retry-After header.

Machine-readable: openapi.json (OpenAPI 3.1, regenerated on each deploy).

Skills

GET /api/skills/search

Public. Full-text search across the skill catalog.

curl "https://recipes.wisechef.ai/api/skills/search?q=seo+audit&page_size=10"

Query params:

• q — full-text on title + description (optional)
• page_size — 1–100, default 20
• page — 1+ (default 1)
• category — marketing | code | web-scraping | ops | sales | sim-robotics
• tier — free | cook | operator
• sort — updated_at | created_at | title | quality_score (default: quality_score)
• is_public — true | false

Response 200:

{
  "total": 63,
  "results": [
    {
      "slug": "seo-audit-engine",
      "title": "SEO Audit Engine",
      "tier": "cook",
      "quality_score": 0.92,
      "install_count_total": 847,
      "last_verified": "2026-05-01",
      "category": "marketing"
    }
  ]
}

GET /api/skills/{slug}

Public. Skill detail — full description, screenshots, version, install count.

curl "https://recipes.wisechef.ai/api/skills/super-memory"

Response: SkillDetailOut — same fields as summary plus version, screenshots, changelog, external_resources.

Errors: 404 if slug not found.

GET /api/skills/install

Auth required (every install needs a key — including free-tier skills).

curl -H "x-api-key: $RECIPES_API_KEY" \
  "https://recipes.wisechef.ai/api/skills/install?slug=super-memory&mode=files"

Query params:

• slug — skill slug (required)
• mode — always pass files
• version — pin to a specific version (optional; defaults to latest)

Response 200:

{
  "slug": "super-memory",
  "version": "1.4.2",
  "tarball_url": "https://cdn.wisechef.ai/skills/super-memory-1.4.2.tar.gz?token=...",
  "manifest": {
    "files": [
      {"path": "SKILL.md", "sha256": "abc123..."},
      {"path": "scripts/setup.sh", "sha256": "def456..."}
    ],
    "signature": "ed25519:base64...",
    "signed_at": "2026-05-01T00:00:00Z"
  }
}

Errors: 401 (no/invalid key), 403 (tier required), 404 (slug not found).

GET /api/skills/access

Auth required. Pre-flight check before install — confirms tier without consuming an install slot.

curl -H "x-api-key: $RECIPES_API_KEY" \
  "https://recipes.wisechef.ai/api/skills/access?slug=seo-audit-engine"

Response — access granted:

{"access": true, "tier": "cook", "slug": "seo-audit-engine"}

Response — access denied:

{"access": false, "reason": "tier_required",
 "required_tier": "cook", "upgrade_url": "/pricing"}

GET /api/skills/trending

Public. Returns trending skills by install velocity.

curl "https://recipes.wisechef.ai/api/skills/trending?period=week&limit=10"

Query params: period (week | month), limit (1–50).

Carousel

GET /api/carousel/today

Public. Returns today's 7 active carousel entries (refreshed daily at 05:00 London).

curl "https://recipes.wisechef.ai/api/carousel/today"

Response 200:

{
  "date": "2026-05-20",
  "entries": [
    {
      "slot": 1,
      "skill": {"slug": "super-memory", "title": "Super Memory"},
      "role": "todays-pick",
      "tagline": "Durable cross-session memory in 60 seconds",
      "archives_at": "2026-05-27T05:00:00Z"
    }
  ]
}

GET /api/carousel/{YYYY-MM-DD}

Public. Historical carousel for a specific date. Permalinkable.

curl "https://recipes.wisechef.ai/api/carousel/2026-05-01"

Errors: 404 if no carousel exists for that date.

Bundles

All bundle endpoints require auth (x-api-key header).

POST /api/cookbooks

Create a new cookbook.

curl -X POST -H "x-api-key: $RECIPES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Team Bundle"}' \
  https://recipes.wisechef.ai/api/cookbooks

Response: 201 with bundle object including id.

GET /api/cookbooks

List all bundles for the authenticated account.

GET /api/cookbooks/{cookbook_id}

Get a single bundle with its skill list and version pins.

POST /api/cookbooks/{cookbook_id}/skills

Add a skill to a bundle (pins to current latest version).

curl -X POST -H "x-api-key: $RECIPES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "seo-audit-engine"}' \
  "https://recipes.wisechef.ai/api/cookbooks/UUID/skills"

DELETE /api/cookbooks/{cookbook_id}/skills/{slug}

Remove a skill from a cookbook.

GET /api/cookbooks/{cookbook_id}/sync

Get the latest-version diff for all skills in the cookbook.

GET /api/cookbooks/{cookbook_id}/manifest

Get the full skill manifest (slugs + pinned versions + checksums).

API Keys

POST /api-keys

Create a new rec_ API key.

curl -X POST -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI server"}' \
  https://recipes.wisechef.ai/api-keys

Response: 201 — key shown once, store securely.

{"key": "rec_...", "id": "uuid", "name": "CI server"}

GET /api-keys

List all API keys (hashed — raw keys not re-shown).

DELETE /api-keys/{key_id}

Revoke an API key immediately. Inflight requests 401 within 60s.

Telemetry

POST /api/telemetry

Auth required. Anonymous-aggregate event reporting. Called automatically by the meta-skill.

{
  "event": "skill_use",
  "slug": "super-memory",
  "result": "success",
  "duration_s": 47,
  "agent_class_hash": "sha256:..."
}

Skill publishing

POST /api/publish/request

Auth required. Submit a skill for review (CLI path — use the MCP tool recipes_publish_request for the agent-first path). Rate limited to 1 per 24h per (user, slug). See Publishing docs.

Error codes

Code	Meaning
200	Success
201	Created (POST endpoints)
400	Missing or invalid parameters
401	Invalid or missing API key
403	Subscription required (skill is premium)
404	Skill / bundle / resource not found
429	Rate limited — check Retry-After header
503	Temporary service issue — retry with backoff

OpenAPI spec

The full OpenAPI 3.1 spec is available at https://recipes.wisechef.ai/openapi.json and is regenerated on each API deploy. Import it into Postman, Insomnia, or use it to generate typed client SDKs.