From 73a7ac36c5170f541f94b112edf7a6ff9cb0269e Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sat, 18 Apr 2026 04:42:28 -0400 Subject: [PATCH 1/2] docs: fix skill naming and refresh getting-started MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README: - Fix broken skill links: chartmetric → chart-metric, songwriting → song-writing - Remove brand-guidelines row (skill does not exist in this repo) getting-started: - Drop the CLI install step — everything is HTTP (REST + MCP) - Add quick-reference header with base URL, MCP URL, and auth headers - Add Path C for dashboard-based key creation at chat.recoupable.com/keys - Replace `recoup whoami` verification with a curl /api/accounts/id example - Add Python and JavaScript REST client examples alongside bash - Add "Auth gotchas" section covering x-api-key vs Bearer, hashing, rotation - Update "What's next" table to match actual folder names Made-with: Cursor --- README.md | 5 +- skills/getting-started/SKILL.md | 101 +++++++++++++++++++++----------- 2 files changed, 69 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 6a366cf..785dbb9 100644 --- a/README.md +++ b/README.md @@ -25,13 +25,12 @@ git clone https://github.com/recoupable/skills.git | [getting-started](skills/getting-started) | Install CLI, get API key, connect via MCP/REST — start here | | [artist-workspace](skills/artist-workspace) | Manage artist directories — context, songs, brand, audience | | [streaming-growth](skills/streaming-growth) | Grow a new artist past streaming milestones that unlock platform tools | -| [brand-guidelines](skills/brand-guidelines) | Apply Recoupable's brand identity to agent outputs | -| [chartmetric](skills/chartmetric) | Query and analyze music data from the Chartmetric API | +| [chart-metric](skills/chart-metric) | Query and analyze music data from the Chartmetric API | | [content-creation](skills/content-creation) | Create social videos, TikToks, Reels, and visual content using AI primitives | | [music-industry-research](skills/music-industry-research) | Music industry research — artist analytics, people search, competitive analysis, web intelligence | | [release-management](skills/release-management) | Plan and execute release campaigns | | [setup-sandbox](skills/setup-sandbox) | Scaffold the workspace for an account's orgs and artists | -| [songwriting](skills/songwriting) | Structured songwriting using the 7 C's method | +| [song-writing](skills/song-writing) | Structured songwriting using the 7 C's method | | [trend-to-song](skills/trend-to-song) | Turn cultural moments into songs and campaign strategies | ## Creating a Skill diff --git a/skills/getting-started/SKILL.md b/skills/getting-started/SKILL.md index 6dd5194..58ee02e 100644 --- a/skills/getting-started/SKILL.md +++ b/skills/getting-started/SKILL.md @@ -1,27 +1,25 @@ --- name: getting-started -description: Set up Recoupable from scratch — install the CLI, get an API key, and make your first call. Use this skill when the user says "set up Recoupable", "install Recoup", "get an API key", "connect to Recoup", "use Recoupable", "onboard to Recoup", "how do I start", or when an agent needs to configure itself to use the Recoupable platform. +description: Set up Recoupable from scratch — get an API key, verify it, and make your first call via REST or MCP. Use this skill when the user says "set up Recoupable", "install Recoup", "get an API key", "connect to Recoup", "use Recoupable", "onboard to Recoup", "how do I start", or when an agent needs to configure itself to use the Recoupable platform. --- # Getting Started with Recoupable -From zero to your first API call in under 2 minutes. Three steps: install, authenticate, use. +From zero to your first API call in under 2 minutes. Two steps: authenticate, call. No install needed — everything is HTTP. -## Step 1 — Install the CLI +- **Base URL:** `https://recoup-api.vercel.app/api` +- **MCP URL:** `https://recoup-api.vercel.app/mcp` +- **Auth header (REST):** `x-api-key: YOUR_RECOUP_API_KEY` +- **Auth header (MCP):** `Authorization: Bearer YOUR_RECOUP_API_KEY` +- **Full docs:** -```bash -npm install -g @recoupable/cli -``` - -Requires Node.js 18+. The CLI wraps the REST API with convenient commands. - -## Step 2 — Get an API key +## Step 1 — Get an API key Two paths depending on who is doing this. ### Path A: Agent (instant, no verification) -POST to the signup endpoint with an `agent+` email. Key comes back immediately. +POST to the signup endpoint with an `agent+` email. The key comes back immediately and is exported for the rest of the session. ```bash export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ @@ -29,7 +27,7 @@ export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agent -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) ``` -The `agent+{unique}@recoupable.com` pattern always returns a key with no verification step. Combining `$(date +%s)` with `$RANDOM` guarantees unique addresses. +The `agent+{unique}@recoupable.com` pattern always returns a key with no verification step. Combining `$(date +%s)` with `$RANDOM` guarantees a unique address. ### Path B: Human (email verification) @@ -41,7 +39,7 @@ curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \ -d '{"email": "user@example.com"}' ``` -This sends a verification code to their email. Ask the user for the code, then: +This sends a verification code to the user's email. Ask the user for the code, then: ```bash curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ @@ -51,39 +49,55 @@ curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \ The response contains the `api_key`. +### Path C: Dashboard (humans only, optional) + +Prefer clicking over scripting? Create a key at [chat.recoupable.com/keys](https://chat.recoupable.com/keys). + +1. Sign in +2. Enter a descriptive name (e.g. "Production Server") +3. Click **Create API Key** and copy it immediately — it's only shown once. + ### Save the key -Add to shell profile so it persists: +Add it to the shell profile so it survives new sessions: ```bash echo 'export RECOUP_API_KEY="recoup_sk_..."' >> ~/.zshrc source ~/.zshrc ``` -## Step 3 — Verify it works +## Step 2 — Verify it works + +Hit the "whoami" endpoint. It echoes the account ID the key belongs to: ```bash -recoup whoami +curl -s "https://recoup-api.vercel.app/api/accounts/id" \ + -H "x-api-key: $RECOUP_API_KEY" ``` -Should print your account ID and email. If it does, you're ready. +A `200` with an `accountId` in the body means you're ready. `401` means the key is missing or wrong. -## First useful command +## First useful call — research any artist -Research any artist: +Research runs entirely over REST. Everything sits under `/api/research/*`. ```bash -recoup research "Drake" +curl -s "https://recoup-api.vercel.app/api/research?q=Drake&type=artists&beta=true" \ + -H "x-api-key: $RECOUP_API_KEY" | jq ``` -Returns structured data: streaming metrics, audience demographics, social traction, career history — pulled from 14 platforms. +That returns ranked matches with Chartmetric IDs. To get a full profile: -## Connect via MCP +```bash +curl -s "https://recoup-api.vercel.app/api/research/profile?artist=Drake" \ + -H "x-api-key: $RECOUP_API_KEY" | jq +``` + +For the full research surface — metrics, audience, cities, similar artists, playlists, charts, people search, deep research, URL extraction, structured enrichment — use the `music-industry-research` skill. -For AI tools that support MCP (Claude, Cursor, etc.): +## Connect via MCP -- **URL:** `https://recoup-api.vercel.app/mcp` -- **Auth:** Bearer token — use your API key as the token +For AI tools that speak MCP (Claude, Cursor, etc.), point them at the Recoup MCP server and pass the API key as a Bearer token: ```json { @@ -98,30 +112,49 @@ For AI tools that support MCP (Claude, Cursor, etc.): } ``` -This gives your AI tool access to 40+ music intelligence tools. +This gives the tool access to Recoup's MCP tools — sandbox execution, research, and more. See the [MCP docs](https://developers.recoupable.com/mcp) for the current tool list and schemas. ## Connect via REST API -Base URL: `https://recoup-api.vercel.app/api` - -Auth header: `x-api-key: YOUR_RECOUP_API_KEY` +Every endpoint follows the same pattern: `https://recoup-api.vercel.app/api/` with `x-api-key` for auth. A minimal REST client in any language: ```bash -curl "https://recoup-api.vercel.app/api/research?q=Drake" \ +curl -s "https://recoup-api.vercel.app/api/tasks" \ -H "x-api-key: $RECOUP_API_KEY" ``` -Full API reference: https://developers.recoupable.com +```python +import os, requests +headers = {"x-api-key": os.environ["RECOUP_API_KEY"]} +r = requests.get("https://recoup-api.vercel.app/api/tasks", headers=headers) +print(r.json()) +``` + +```javascript +const r = await fetch("https://recoup-api.vercel.app/api/tasks", { + headers: { "x-api-key": process.env.RECOUP_API_KEY }, +}); +console.log(await r.json()); +``` + +Full reference (all resources, request/response shapes, auth rules): + +## Auth gotchas + +- Use `x-api-key` for server-to-server, or `Authorization: Bearer ` for frontend sessions via Privy. **Never both in the same request** — the API returns `401`. +- API keys are personal by default. If your account is in an organization, you can pass `account_id` on supported endpoints to access other accounts in that org. +- Keys are hashed (HMAC-SHA256) on save — if you lose the key, you rotate it, not recover it. Rotate at [chat.recoupable.com/keys](https://chat.recoupable.com/keys). ## What's next After setup, use these skills for specific workflows: | Skill | What it does | -|-------|-------------| +| ----- | ------------ | +| music-industry-research | Deep artist analytics, people search, charts, competitive analysis, web intelligence | | content-creation | Generate videos, images, captions from artist catalogs | -| industry-research | Deep artist analytics, people search, competitive analysis | | release-management | Plan and execute release campaigns | -| setup-sandbox | Scaffold workspace for an account's orgs and artists | +| setup-sandbox | Scaffold the workspace for an account's orgs and artists | | streaming-growth | Grow artists past streaming milestones | | songwriting | Structured songwriting using the 7 C's method | +| artist-workspace | Manage artist directories — context, songs, brand, audience | From 2ed072e58c05394e7a4973c0852e98818d16ef50 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Sat, 18 Apr 2026 12:12:14 -0400 Subject: [PATCH 2/2] docs: clarify agent+ signup creates a separate account MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two corrections to Path A based on a live audit against prod and a read of the canonical authentication.mdx + agents.mdx in the docs worktree (feat/docs-design-overhaul-combined): - Soften "always returns a key" → "skips email verification and returns a key on the first call". The signup handler routes pre-existing agent+ emails through the existing-account path, so the unconditional "always" was technically incorrect even though the date+RANDOM trick makes collision impossible in practice. - Add a warning that agent+ emails create a brand-new sandboxed account that is NOT linked to the human's real email. This is the same warning that already lives in docs/agents.mdx — agents using agent+sid@recoupable.com would otherwise think they are working as Sid when they are actually in an isolated sandbox. Verified live against https://recoup-api.vercel.app: - /api/agents/signup with agent+ email returns api_key immediately - /api/accounts/id returns {status, accountId} (200) - Sending both x-api-key + Authorization returns 401 with the exact message documented in the skill - /api/research?q=Drake&type=artists&beta=true returns ranked Chartmetric matches - /api/research/profile?artist=Drake returns full profile - /api/tasks returns 200 - /mcp endpoint accepts Bearer auth and responds to JSON-RPC initialize as recoup-mcp v0.0.1 with tools capability Verified static against api/lib: - HMAC-SHA256 hashing in lib/keys/hashApiKey.ts - Org-account access semantics in lib/organizations/canAccessAccount.ts match the skill's "any account in your org" wording Made-with: Cursor --- skills/getting-started/SKILL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/skills/getting-started/SKILL.md b/skills/getting-started/SKILL.md index 58ee02e..9178b58 100644 --- a/skills/getting-started/SKILL.md +++ b/skills/getting-started/SKILL.md @@ -19,7 +19,7 @@ Two paths depending on who is doing this. ### Path A: Agent (instant, no verification) -POST to the signup endpoint with an `agent+` email. The key comes back immediately and is exported for the rest of the session. +POST to the signup endpoint with a fresh `agent+` email. The key comes back immediately and is exported for the rest of the session. ```bash export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \ @@ -27,7 +27,9 @@ export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agent -d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key) ``` -The `agent+{unique}@recoupable.com` pattern always returns a key with no verification step. Combining `$(date +%s)` with `$RANDOM` guarantees a unique address. +A new `agent+{unique}@recoupable.com` address skips email verification and returns a key on the first call. Combining `$(date +%s)` with `$RANDOM` guarantees uniqueness so you never collide with an existing account. + +> ⚠️ **`agent+` emails create a separate account.** `agent+sid@recoupable.com` is **not** linked to `sid@recoupable.com` — it's a brand-new sandboxed account with no roster, no orgs, and no history. To work on behalf of an existing human, use **Path B** with their real email. ### Path B: Human (email verification)