# Agents
Source: https://developers.recoupable.com/agents
Programmatic agent onboarding — sign up and obtain API keys in one call, no dashboard, no human in the loop.
## Quickest start
Get a working API key in a single unauthenticated request:
```bash theme={null}
curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-H "Content-Type: application/json" \
-d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}'
```
Response:
```json theme={null}
{
"account_id": "123e4567-e89b-12d3-a456-426614174000",
"api_key": "recoup_sk_abc123...",
"message": "If this is a new agent+ email, your API key is included. Otherwise, check your email for a verification code."
}
```
That's it. Store `api_key`, pass it in the `x-api-key` header on every subsequent request, and you're done.
**One-liner — sign up and export the key in one shot.** Drop this into your shell and you'll have `$RECOUP_API_KEY` ready to use on the next line:
```bash theme={null}
export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-H "Content-Type: application/json" \
-d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
```
Verify it worked:
```bash theme={null}
curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id
```
The `agent+{unique-suffix}@recoupable.com` shape is the recommended path for agents — it always returns an API key instantly, with no email verification required. Combining `$(date +%s)` with `$RANDOM` guarantees a fresh, collision-free address on every call (including multiple signups within the same second) and is portable across macOS and Linux shells.
## How it works
Two unauthenticated endpoints power agent onboarding:
* **[`POST /api/agents/signup`](/api-reference/agents/signup)** — Register with an email address. Emails with the `agent+` prefix that have never been seen before receive an API key immediately. Any other email (or a previously-used `agent+` address) receives a 6-digit verification code via email.
* **[`POST /api/agents/verify`](/api-reference/agents/verify)** — Submit the verification code to receive an API key.
Multiple API keys per account are supported — each signup or verification generates a new key without revoking existing ones.
## Standard signup (email verification)
If you're building a human-facing integration and want the user to verify their real email, use any non-`agent+` address:
Step 1 — request a verification code:
```bash theme={null}
curl -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com"}'
```
Step 2 — submit the 6-digit code from the verification email:
```bash theme={null}
curl -X POST "https://recoup-api.vercel.app/api/agents/verify" \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "code": "123456"}'
```
Response:
```json theme={null}
{
"account_id": "123e4567-e89b-12d3-a456-426614174000",
"api_key": "recoup_sk_abc123...",
"message": "Verified"
}
```
## Using your API key
Pass the returned `api_key` in the `x-api-key` header on every authenticated request:
```bash theme={null}
curl -X GET "https://recoup-api.vercel.app/api/tasks" \
-H "x-api-key: YOUR_API_KEY"
```
See [Authentication](/authentication) for the full authentication model, including organization access and Bearer token support, and [Quickstart](/quickstart) for your first end-to-end request.
# Add Artist to Account
Source: https://developers.recoupable.com/api-reference/accounts/add-artist
/api-reference/openapi/accounts.json POST /api/accounts/artists
Add an artist to an account's list of associated artists. If the artist is already associated with the account, returns success without modification.
# Create Account
Source: https://developers.recoupable.com/api-reference/accounts/create
/api-reference/openapi/accounts.json POST /api/accounts
Create a new account or retrieve an existing account by email or wallet address. If an account with the provided email or wallet already exists, returns that account. Otherwise creates a new account and initializes credits.
# Get Account
Source: https://developers.recoupable.com/api-reference/accounts/get
/api-reference/openapi/accounts.json GET /api/accounts/{id}
Retrieve detailed account information by ID. Returns the account with associated profile info, emails, and wallet addresses.
# Get Account ID
Source: https://developers.recoupable.com/api-reference/accounts/id
/api-reference/openapi/accounts.json GET /api/accounts/id
Retrieve the ID of the authenticated account associated with the provided credentials. This is useful when you have an API key or access token but do not yet know the corresponding accountId.
# Update Account
Source: https://developers.recoupable.com/api-reference/accounts/update
/api-reference/openapi/accounts.json PATCH /api/accounts
Update an existing account's profile information including name, organization, image, instruction, job title, role type, company name, and knowledges. Requires authentication via x-api-key or Authorization Bearer token. The authenticated account may update itself or a permitted account_id override.
# List Agent Sign-Ups (Admin)
Source: https://developers.recoupable.com/api-reference/admins/agent-signups
/api-reference/openapi/accounts.json GET /api/admins/agent/signups
Returns API key sign-up records created by AI agents. Agent sign-ups are identified by the agent+ email prefix in the associated account email. Supports period filtering and returns individual API key records with their associated email and creation timestamp, suitable for building sign-up trend charts. Requires admin authentication.
# List Pro Artists (Admin)
Source: https://developers.recoupable.com/api-reference/admins/artists-pro
/api-reference/openapi/accounts.json GET /api/admins/artists/pro
Retrieve the deduplicated list of artist IDs owned by pro accounts. An account is "pro" when its email belongs to an enterprise domain or it has an active Stripe subscription. Admin-scoped: requires an admin-flagged API key because the response identifies paying customer accounts.
# Check Admin Status
Source: https://developers.recoupable.com/api-reference/admins/check
/api-reference/openapi/accounts.json GET /api/admins
Check if the authenticated account is a Recoup admin. An account is considered an admin if it is a member of the Recoup organization. No input parameters required — authentication is performed via the x-api-key or Authorization header.
# List Coding Agent Slack Tags (Admin)
Source: https://developers.recoupable.com/api-reference/admins/coding-agent-slack-tags
/api-reference/openapi/accounts.json GET /api/admins/coding/slack
Returns a list of Slack mentions of the Recoup Coding Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any GitHub pull request URLs opened in response. Also returns aggregate pull request statistics. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.
# Get Coding Agent PR Merged Status (Admin)
Source: https://developers.recoupable.com/api-reference/admins/coding-pr
/api-reference/openapi/accounts.json GET /api/admins/coding/pr
Returns the status (open, closed, or merged) for each provided GitHub pull request URL. Accepts one or more `pull_requests` query parameters containing GitHub PR URLs. Uses the GitHub REST API to check each pull request's state. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.
# List Content Agent Slack Tags (Admin)
Source: https://developers.recoupable.com/api-reference/admins/content-slack-tags
/api-reference/openapi/accounts.json GET /api/admins/content/slack
Returns a list of Slack mentions of the Recoup Content Agent bot, pulled directly from the Slack API as the source of truth. Each entry includes the tagger's information, the prompt they sent, the timestamp, the channel, and any video link responses. Also returns aggregate video statistics for measuring tag-to-video conversion. Supports optional time-period filtering. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.
# List Account Emails (Admin)
Source: https://developers.recoupable.com/api-reference/admins/emails
/api-reference/openapi/accounts.json GET /api/admins/emails
Returns Resend emails including HTML content. Provide either account_id (returns all emails for an account) or email_id (returns a single email by Resend ID). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token. Email response shape matches the [Resend Retrieve Email API](https://resend.com/docs/api-reference/emails/retrieve-email).
# List Privy Logins (Admin)
Source: https://developers.recoupable.com/api-reference/admins/privy
/api-reference/openapi/accounts.json GET /api/admins/privy
Returns Privy login statistics for a given time period. Results include counts for new accounts (created_at), active accounts (latest_verified_at), total Privy accounts across all time, and the full, unmodified Privy account objects. See [Privy User object documentation](https://docs.privy.io/api-reference/users/get-all) for the complete type definition. Defaults to period=all (no date filter). Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.
# List Account Sandboxes (Admin)
Source: https://developers.recoupable.com/api-reference/admins/sandboxes
/api-reference/openapi/accounts.json GET /api/admins/sandboxes
Returns a list of all accounts and their sandbox usage statistics. Each item includes the account email, total number of sandboxes created, and the timestamp of the most recently created sandbox. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.
# List Org Repo Stats (Admin)
Source: https://developers.recoupable.com/api-reference/admins/sandboxes-orgs
/api-reference/openapi/accounts.json GET /api/admins/sandboxes/orgs
Returns commit statistics for each repository in the recoupable GitHub organization. Each item includes the repo name, URL, total commit count, latest 5 commit messages, earliest and latest commit timestamps, and the list of account repo URLs that include this org repo as a submodule. Requires the authenticated account to be a Recoup admin. Authentication via x-api-key or Authorization Bearer token.
# Agent Signup
Source: https://developers.recoupable.com/api-reference/agents/signup
/api-reference/openapi/accounts.json POST /api/agents/signup
Register an agent. For new agent+ emails, returns an API key immediately. For all other cases, sends a verification code to the email — call [POST /api/agents/verify](/api-reference/agents/verify) with the code to get your API key.
**Tip:** If you're unsure what email to register, generate a unique `agent+{suffix}@recoupable.com` address (e.g. `agent+1744410896-28439@recoupable.com`, combining a Unix timestamp with a random integer). This guarantees a fresh `agent+` address on every call — including multiple signups within the same second — and returns an API key instantly with no email verification required.
# Verify Agent Email
Source: https://developers.recoupable.com/api-reference/agents/verify
/api-reference/openapi/accounts.json POST /api/agents/verify
Verify an agent's email with the code sent during signup. Returns an API key on success.
# Scraper Results
Source: https://developers.recoupable.com/api-reference/apify/scraper
/api-reference/openapi/social.json GET /api/apify/runs/{runId}
Check the status and retrieve results from Apify scraper runs. This endpoint uses the Apify API Client to fetch the current status of a scraper run and its results if available. Use the runId returned from endpoints like Instagram Comments, Instagram Profiles, Social Scrape, or Artist Socials Scrape to poll for results.
# Get Artist Profile
Source: https://developers.recoupable.com/api-reference/artist/profile
/api-reference/openapi/releases.json GET /api/artist-profile
Retrieve comprehensive profile information for an artist across all connected social media platforms, including profile details and post metrics.
# Socials scrape
Source: https://developers.recoupable.com/api-reference/artist/socials-scrape
post /api/artist/socials/scrape
Trigger scrape jobs for all social profiles linked to an artist. Provide an artist_account_id, and the API will look up the artist's socials and invoke a scraping job for each social profile. Each scrape returns Apify run metadata so you can poll for status and retrieve results.
# Create Artist
Source: https://developers.recoupable.com/api-reference/artists/create
/api-reference/openapi/releases.json POST /api/artists
Create a new artist account. The artist can optionally be linked to an organization.
# Delete Artist
Source: https://developers.recoupable.com/api-reference/artists/delete
/api-reference/openapi/releases.json DELETE /api/artists/{id}
Delete an artist accessible to the authenticated account.
# Get Artists
Source: https://developers.recoupable.com/api-reference/artists/list
/api-reference/openapi/releases.json GET /api/artists
Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to.
# Pin Artist
Source: https://developers.recoupable.com/api-reference/artists/pin
/api-reference/openapi/releases.json POST /api/artists/{id}/pin
Pin an artist. This updates the caller's pinned preference for the artist.
# Get Artist Socials
Source: https://developers.recoupable.com/api-reference/artists/socials
/api-reference/openapi/releases.json GET /api/artists/{id}/socials
Retrieve all social media profiles associated with an artist. This endpoint should be called before using the Social Posts endpoint to obtain the necessary social IDs.
# Unpin Artist
Source: https://developers.recoupable.com/api-reference/artists/unpin
/api-reference/openapi/releases.json DELETE /api/artists/{id}/pin
Unpin an artist. This updates the caller's pinned preference for the artist.
# Update Artist
Source: https://developers.recoupable.com/api-reference/artists/update
/api-reference/openapi/releases.json PATCH /api/artists/{id}
Update an artist. All body fields are optional, but at least one must be provided. Use this endpoint to set basic profile (name, image, label), AI instructions, knowledge base entries, social profile URLs (mapped by platform), and pinned state for the calling account.
# Get Chat Artist
Source: https://developers.recoupable.com/api-reference/chat/artist
/api-reference/openapi/research.json GET /api/chats/{id}/artist
Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller.
# Get Chats
Source: https://developers.recoupable.com/api-reference/chat/chats
/api-reference/openapi/research.json GET /api/chats
Retrieve chat rooms (conversations) for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations. Optionally filter by an artist_account_id. The endpoint returns metadata about each room, including the topic, associated artist, and last updated timestamp.
# Compact Chats
Source: https://developers.recoupable.com/api-reference/chat/compact
/api-reference/openapi/research.json POST /api/chats/compact
Compact one or more chat conversations into summarized versions. This reduces the size of chat history while preserving key information. Optionally provide a prompt to control what information gets preserved in the compacted summary.
# Create Chat
Source: https://developers.recoupable.com/api-reference/chat/create
post /api/chats
Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to.
# Delete Chat
Source: https://developers.recoupable.com/api-reference/chat/delete
delete /api/chats
Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself.
# Generate Chat
Source: https://developers.recoupable.com/api-reference/chat/generate
post /api/chat/generate
Generate AI-powered text responses using the Recoup chat system. This endpoint processes chat requests and returns generated text along with metadata about the generation process.
# Get Chat Messages
Source: https://developers.recoupable.com/api-reference/chat/messages
/api-reference/openapi/research.json GET /api/chats/{id}/messages
Retrieve all messages (memories) for a specific chat room in chronological order.
# Copy Chat Messages
Source: https://developers.recoupable.com/api-reference/chat/messages-copy
/api-reference/openapi/research.json POST /api/chats/{id}/messages/copy
Copy all messages from the source chat (`id` path param) to a target chat (`targetChatId` in request body). By default, existing target messages are cleared before copy.
# Delete Trailing Chat Messages
Source: https://developers.recoupable.com/api-reference/chat/messages-trailing-delete
/api-reference/openapi/research.json DELETE /api/chats/{id}/messages/trailing
Delete all messages in a chat from a given message onward (inclusive), identified by `from_message_id`.
# Stream Chat
Source: https://developers.recoupable.com/api-reference/chat/stream
post /api/chat
Stream AI-powered chat responses using the Recoup chat system. This endpoint mirrors the request payload of the Chat Generate API but returns a streaming response compatible with the Vercel AI SDK `createUIMessageStreamResponse`. The stream emits UI message parts encoded as data chunks that can be parsed with `createUIMessageStreamParser`.
# Update Chat
Source: https://developers.recoupable.com/api-reference/chat/update
patch /api/chats
Update a chat room's topic (display name). The chatId is required; the topic field will be updated. Topic must be between 3 and 50 characters.
# Get Comments
Source: https://developers.recoupable.com/api-reference/comments/get
/api-reference/openapi/social.json GET /api/comments
Retrieve comments associated with an artist or a specific post, with support for pagination. This endpoint returns raw comment data including the comment text, associated post, and commenter's social profile reference.
# Authorize Connector
Source: https://developers.recoupable.com/api-reference/connectors/authorize
/api-reference/openapi/social.json POST /api/connectors
Generate an OAuth authorization URL for connecting a third-party service. Redirect to the returned URL to complete the OAuth flow.
# Disconnect Connector
Source: https://developers.recoupable.com/api-reference/connectors/disconnect
/api-reference/openapi/social.json DELETE /api/connectors
Disconnect a connected account from a third-party service. This revokes the OAuth connection and removes stored credentials.
# Execute Connector Action
Source: https://developers.recoupable.com/api-reference/connectors/execute-action
/api-reference/openapi/social.json POST /api/connectors/actions
Execute a connector action with the given parameters. The `actionSlug` must come from a prior call to GET /api/connectors/actions, and `parameters` must match the `parameters` JSON Schema returned for that action. The action's parent connector must be currently connected (`isConnected: true` in the catalog) — otherwise this endpoint returns 409. The `result` field passes through whatever the underlying connector returns; its shape is action-specific.
# List Connectors
Source: https://developers.recoupable.com/api-reference/connectors/list
/api-reference/openapi/social.json GET /api/connectors
List available connectors and their connection status. Returns all supported third-party integrations (e.g., Google Sheets, TikTok) along with whether they are currently connected.
# List Connector Actions
Source: https://developers.recoupable.com/api-reference/connectors/list-actions
/api-reference/openapi/social.json GET /api/connectors/actions
List the executable actions available across the authenticated account's connectors. Each action is a single tool that can be invoked via POST /api/connectors/actions — for example, the `googlesheets` connector exposes actions like `GOOGLESHEETS_WRITE_SPREADSHEET`. Actions whose parent connector is not yet connected are returned with `isConnected: false` and cannot be executed until the connector is authorized via POST /api/connectors.
# Task Callback
Source: https://developers.recoupable.com/api-reference/content-agent/callback
/api-reference/openapi/content.json POST /api/content-agent/callback
Internal callback endpoint for the `poll-content-run` Trigger.dev task. Receives content generation results and posts them back to the originating Slack thread. Authenticated via the `x-callback-secret` header.
This endpoint is not intended for external use — it is called automatically by the polling task when content runs complete, fail, or time out.
# Slack Webhook
Source: https://developers.recoupable.com/api-reference/content-agent/webhook
/api-reference/openapi/content.json POST /api/content-agent/{platform}
Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for ` [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.
For Slack, also handles `url_verification` challenges during app setup.
# Analyze Video
Source: https://developers.recoupable.com/api-reference/content/analyze-video
/api-reference/openapi/content.json POST /api/content/analyze
Analyze a video and answer questions about it. Pass a video URL and a text prompt — for example, "Describe what happens" or "Rate the visual quality 1-10." Returns the generated text.
# Create Content
Source: https://developers.recoupable.com/api-reference/content/create
/api-reference/openapi/content.json POST /api/content/create
Trigger the content creation pipeline for an artist. Provide `artist_account_id` to identify the target artist. Validates the artist has all required files (face guide, songs) unless overridden via `songs` URLs or `images`, then triggers a background task that generates a short-form video. Returns `runIds` — an array of run IDs that can each be polled via [GET /api/tasks/runs](/api-reference/tasks/runs).
# Edit Content
Source: https://developers.recoupable.com/api-reference/content/edit
/api-reference/openapi/content.json PATCH /api/content
Apply ffmpeg edits to a video — trim, crop, resize, or overlay text. Pass a `template` for a preset edit pipeline, or build your own with an `operations` array.
# Estimate Cost
Source: https://developers.recoupable.com/api-reference/content/estimate
/api-reference/openapi/content.json GET /api/content/estimate
Estimate the cost of running the content creation pipeline. Calculates per-step and per-video costs based on current pricing. Supports comparing multiple workflow profiles (e.g., premium vs. budget) and projecting batch costs. This endpoint is informational only — it does not trigger any pipeline execution or spend credits.
# Generate Caption
Source: https://developers.recoupable.com/api-reference/content/generate-caption
/api-reference/openapi/content.json POST /api/content/caption
Generate a short caption from a topic. Returns the text content and default styling (font, color, size).
# Generate Image
Source: https://developers.recoupable.com/api-reference/content/generate-image
/api-reference/openapi/content.json POST /api/content/image
Generate an image from a text prompt. Pass a `reference_image_url` to guide the output toward a specific look or subject. Returns the image URL.
# Generate Video
Source: https://developers.recoupable.com/api-reference/content/generate-video
/api-reference/openapi/content.json POST /api/content/video
Generate a video. Set `mode` to control what kind of video you get:
- `prompt` — create a video from a text description
- `animate` — animate a still image
- `reference` — use an image as a style/subject reference (not the first frame)
- `extend` — continue an existing video
- `first-last` — generate a video that transitions between two images
- `lipsync` — sync face movement to an audio clip
If `mode` is omitted, it's inferred from the inputs you provide.
# Get Template Detail
Source: https://developers.recoupable.com/api-reference/content/template-detail
/api-reference/openapi/content.json GET /api/content/templates/{id}
Get the full configuration for a specific content creation template. Returns the complete creative recipe including image prompts, video motion config, caption style rules, and edit operations.
# List Templates
Source: https://developers.recoupable.com/api-reference/content/templates
/api-reference/openapi/content.json GET /api/content/templates
List all available content creation templates. Templates are optional — every content primitive works without one. When you do use a template, it provides a complete creative recipe: image prompts, video motion config, caption style rules, and edit operations. Returns template ID and description only — enough to pick the right one.
# Transcribe Audio
Source: https://developers.recoupable.com/api-reference/content/transcribe-audio
/api-reference/openapi/content.json POST /api/content/transcribe
Transcribe audio into text with word-level timestamps. Pass one or more audio file URLs in `audio_urls`. Returns the full transcript and an array of timed segments.
# Upscale Content
Source: https://developers.recoupable.com/api-reference/content/upscale
/api-reference/openapi/content.json POST /api/content/upscale
Upscale an image or video to higher resolution. Pass the URL and specify the type. Returns the upscaled URL.
# Validate Artist
Source: https://developers.recoupable.com/api-reference/content/validate
/api-reference/openapi/content.json GET /api/content/validate
Check whether an artist has all the required files to run the content creation pipeline. Returns a structured report of each required and recommended file with its status. Required files must be present or the pipeline will fail. Recommended files improve output quality but are not strictly necessary. Provide `artist_account_id` as a query parameter.
# Get Artist Fans
Source: https://developers.recoupable.com/api-reference/fans/get
/api-reference/openapi/releases.json GET /api/artists/{id}/fans
Retrieve all social profiles from fans of an artist across all platforms. This endpoint aggregates fan data from all connected social media platforms. Supports pagination for large fan lists.
# Generate Image
Source: https://developers.recoupable.com/api-reference/image/generation
/api-reference/openapi/content.json GET /api/image/generate
Generate high-quality images using AI models. Images are automatically stored on Arweave and include In Process moment metadata for provenance and ownership tracking.
# Send Notification
Source: https://developers.recoupable.com/api-reference/notifications/create
/api-reference/openapi/accounts.json POST /api/notifications
Send a notification email to the authenticated account's email address via the Resend API. Emails are sent from `Agent by Recoup `. The recipient is automatically resolved from the API key or Bearer token. Supports plain text (rendered as Markdown) or raw HTML bodies, optional CC recipients, custom headers, and an optional room_id to include a chat link in the email footer.
# Add Artist to Organization
Source: https://developers.recoupable.com/api-reference/organizations/add-artist
/api-reference/openapi/accounts.json POST /api/organizations/artists
Add an artist to an organization. This allows organization members to access and manage the artist. This endpoint is idempotent - calling it multiple times with the same artistId and organizationId will not create duplicate records.
# Create Organization
Source: https://developers.recoupable.com/api-reference/organizations/create
/api-reference/openapi/accounts.json POST /api/organizations
Create a new organization. The creator is automatically added as a member of the organization.
# Get Organizations
Source: https://developers.recoupable.com/api-reference/organizations/list
/api-reference/openapi/accounts.json GET /api/organizations
Retrieve all organizations that the authenticated account belongs to. Pass account_id to retrieve organizations for a specific account the API key has access to.
# Get Artist Posts
Source: https://developers.recoupable.com/api-reference/posts/get
/api-reference/openapi/social.json GET /api/artists/{id}/posts
Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist. Supports pagination for large post collections.
# List Pulses
Source: https://developers.recoupable.com/api-reference/pulses/list
/api-reference/openapi/accounts.json GET /api/pulses
Retrieve pulse information for the authenticated account. If the account has access to organizations, pass account_id to filter to a specific account within those organizations.
# Update Pulse
Source: https://developers.recoupable.com/api-reference/pulses/update
/api-reference/openapi/accounts.json PATCH /api/pulses
Update the pulse settings for an account. Use this to enable or disable the pulse. Returns an array of pulses for consistency with the GET endpoint.
# Albums
Source: https://developers.recoupable.com/api-reference/research/albums
/api-reference/openapi/research.json GET /api/research/albums
Get the album discography — albums, EPs, and singles with release dates — for a Chartmetric `artist_id`.
Thin proxy over Chartmetric's `/artist/:id/albums`. By default `is_primary=true`, so only albums where the artist is a main artist are returned — DJ compilations, soundtracks, and pure feature appearances are excluded. Pass `is_primary=false` to include them. Discover a Chartmetric `artist_id` via [GET /api/research](/api-reference/research/search) with `type=artists&beta=true`.
# Audience Demographics
Source: https://developers.recoupable.com/api-reference/research/audience
/api-reference/openapi/research.json GET /api/research/audience
Get audience demographics for an artist on a specific platform — age, gender, and country breakdown.
# Career Timeline
Source: https://developers.recoupable.com/api-reference/research/career
/api-reference/openapi/research.json GET /api/research/career
Get an artist's career timeline — key milestones, trajectory, and career stage.
# Charts
Source: https://developers.recoupable.com/api-reference/research/charts
/api-reference/openapi/research.json GET /api/research/charts
Get global chart positions for a platform — Spotify, Apple Music, TikTok, YouTube, iTunes, Shazam, etc. NOT artist-scoped. Returns ranked entries with track and artist info.
# Listener Cities
Source: https://developers.recoupable.com/api-reference/research/cities
/api-reference/openapi/research.json GET /api/research/cities
Get the top cities where an artist's fans listen, ranked by listener concentration.
# Curator
Source: https://developers.recoupable.com/api-reference/research/curator
/api-reference/openapi/research.json GET /api/research/curator
Get curator profile — name, image, follower counts across platforms, tag-based genre info, and Chartmetric playlist reach statistics. Requires a numeric Chartmetric curator ID (e.g. `2` for Spotify's own account). Discover a Chartmetric curator ID via [GET /api/research](/api-reference/research/search) with `type=curators&beta=true`. You can also find curators indirectly by looking up their playlists via [GET /api/research/playlists](/api-reference/research/playlists).
# Deep Research
Source: https://developers.recoupable.com/api-reference/research/deep
/api-reference/openapi/research.json POST /api/research/deep
Perform deep, comprehensive research on a topic. Browses multiple sources extensively and returns a cited report. Use for full artist deep dives, competitive analysis, and any research requiring synthesis across many sources.
# Discover Artists
Source: https://developers.recoupable.com/api-reference/research/discover
/api-reference/openapi/research.json GET /api/research/discover
Discover artists by criteria — filter by country, genre, Spotify monthly listener range, and sort by growth metrics.
# Enrich
Source: https://developers.recoupable.com/api-reference/research/enrich
/api-reference/openapi/research.json POST /api/research/enrich
Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `"type": "object"` at the top level — requests without an explicit type will be rejected.
# Extract URL
Source: https://developers.recoupable.com/api-reference/research/extract
/api-reference/openapi/research.json POST /api/research/extract
Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content.
# Festivals
Source: https://developers.recoupable.com/api-reference/research/festivals
/api-reference/openapi/research.json GET /api/research/festivals
List music festivals.
# Genres
Source: https://developers.recoupable.com/api-reference/research/genres
/api-reference/openapi/research.json GET /api/research/genres
List all available genre IDs and names. Use these IDs with the discover endpoint at GET /api/research/discover.
# AI Insights
Source: https://developers.recoupable.com/api-reference/research/insights
/api-reference/openapi/research.json GET /api/research/insights
Get AI-generated insights about an artist — automatically surfaced trends, milestones, and observations.
# Instagram Posts
Source: https://developers.recoupable.com/api-reference/research/instagram-posts
/api-reference/openapi/research.json GET /api/research/instagram-posts
Get an artist's top Instagram posts and reels, sorted by engagement.
# Lookup by URL
Source: https://developers.recoupable.com/api-reference/research/lookup
/api-reference/openapi/research.json GET /api/research/lookup
Look up an artist by a platform URL or ID — Spotify URL, Spotify ID, Apple Music URL, etc.
# Platform Metrics
Source: https://developers.recoupable.com/api-reference/research/metrics
/api-reference/openapi/research.json GET /api/research/metrics
Get platform-specific metrics for an artist over time — followers, listeners, views, engagement. Supports 14 platforms.
# Milestones
Source: https://developers.recoupable.com/api-reference/research/milestones
/api-reference/openapi/research.json GET /api/research/milestones
Get an artist's activity feed — playlist adds, chart entries, and other notable events. Each milestone includes a date, summary, platform, track name, and star rating.
# People Search
Source: https://developers.recoupable.com/api-reference/research/people
/api-reference/openapi/research.json POST /api/research/people
Search for people in the music industry — artists, managers, A&R reps, producers. Returns multi-source profiles including LinkedIn data.
# Playlist
Source: https://developers.recoupable.com/api-reference/research/playlist
/api-reference/openapi/research.json GET /api/research/playlist
Get playlist metadata — name, description, follower count, track count, and curator info.
Thin proxy over Chartmetric's `/playlist/:platform/:id` detail lookup. **`id` is Chartmetric's own numeric playlist ID, not the streaming-platform's native ID.** Discover the Chartmetric playlist ID via [GET /api/research](/api-reference/research/search) with `type=playlists&beta=true` — the `id` field in each result is the Chartmetric ID to pass here.
# Playlist Placements
Source: https://developers.recoupable.com/api-reference/research/playlists
/api-reference/openapi/research.json GET /api/research/playlists
Get an artist's playlist placements — editorial, algorithmic, and indie playlists across platforms.
# Artist Profile
Source: https://developers.recoupable.com/api-reference/research/profile
/api-reference/openapi/research.json GET /api/research/profile
Get a full artist profile — bio, genres, social URLs, label, career stage, and basic metrics.
# Radio Stations
Source: https://developers.recoupable.com/api-reference/research/radio
/api-reference/openapi/research.json GET /api/research/radio
List radio stations tracked by Chartmetric. NOT artist-scoped. Returns station names, formats, and markets.
# Artist Rank
Source: https://developers.recoupable.com/api-reference/research/rank
/api-reference/openapi/research.json GET /api/research/rank
Get an artist's global Chartmetric ranking as a single integer value.
# Search
Source: https://developers.recoupable.com/api-reference/research/search
/api-reference/openapi/research.json GET /api/research
Unified Chartmetric search. This is the discovery primitive for the detail-lookup endpoints — use `type=artists` to find an `id` for [GET /api/research/albums](/api-reference/research/albums), `type=tracks` for [GET /api/research/track](/api-reference/research/track), `type=playlists` for [GET /api/research/playlist](/api-reference/research/playlist), etc. Pick the right `id` from the returned results and pass it to the appropriate detail endpoint.
Thin proxy over Chartmetric's `/search`. Chartmetric's default search engine is narrow — for ambiguous queries like `Hotline Bling` or `Flowers` it often returns a single low-quality match. **Pass `beta=true` for higher relevance and accuracy**, which switches Chartmetric to its improved ranking engine. Beta results include a numeric `match_strength` score and have a slightly different shape than the default engine (see the response schema).
# Similar Artists
Source: https://developers.recoupable.com/api-reference/research/similar
/api-reference/openapi/research.json GET /api/research/similar
Find similar artists based on audience overlap, genre, mood, and musicality. Use for competitive analysis and collaboration discovery.
# Track
Source: https://developers.recoupable.com/api-reference/research/track
/api-reference/openapi/research.json GET /api/research/track
Get full Chartmetric track metadata by numeric track `id` — title, artists, albums, release date, genres, popularity, and platform IDs.
This endpoint is a thin proxy over Chartmetric's `/track/:id` detail lookup. Discover a Chartmetric track ID via [GET /api/research](/api-reference/research/search) with `type=tracks&beta=true` — pick a result's `id`, then call this endpoint. Keeping the two concerns separate means predictable credit charging and no silent wrong-match behavior for ambiguous queries.
# Track Playlists
Source: https://developers.recoupable.com/api-reference/research/track-playlists
/api-reference/openapi/research.json GET /api/research/track/playlists
Returns playlists featuring a specific track. Accepts a Chartmetric track ID (`id`) or a track name + optional artist (`q`, `artist`) for a Spotify-powered lookup. When no filter flag is passed, defaults to editorial + indie + majorCurator + popularIndie = `true`. Costs 5 credits per request.
Discover a Chartmetric track `id` via [GET /api/research](/api-reference/research/search) with `type=tracks&beta=true` — then pass the resulting `id` here for the most reliable match (avoids the ambiguity of name-based lookup).
# Tracks
Source: https://developers.recoupable.com/api-reference/research/tracks
/api-reference/openapi/research.json GET /api/research/tracks
Get all tracks by an artist with popularity data.
# Social URLs
Source: https://developers.recoupable.com/api-reference/research/urls
/api-reference/openapi/research.json GET /api/research/urls
Get all social and streaming URLs for an artist — Spotify, Instagram, TikTok, YouTube, Twitter, SoundCloud, and more.
# Venues
Source: https://developers.recoupable.com/api-reference/research/venues
/api-reference/openapi/research.json GET /api/research/venues
Get venues an artist has performed at, including capacity and location data.
# Web Search
Source: https://developers.recoupable.com/api-reference/research/web
/api-reference/openapi/research.json POST /api/research/web
Search the web for real-time information. Returns ranked results with titles, URLs, and content snippets. Use for narrative context, press coverage, and cultural research that structured data endpoints don't cover.
# Create Sandbox
Source: https://developers.recoupable.com/api-reference/sandboxes/create
/api-reference/openapi/content.json POST /api/sandboxes
Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run ""` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.
# Delete Sandbox
Source: https://developers.recoupable.com/api-reference/sandboxes/delete
/api-reference/openapi/content.json DELETE /api/sandboxes
Delete a sandbox environment for the authenticated account. This permanently deletes the associated GitHub repository and removes the account's snapshot record from the database. By default, deletes the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.
# Get File Contents
Source: https://developers.recoupable.com/api-reference/sandboxes/file
/api-reference/openapi/content.json GET /api/sandboxes/file
Retrieve the raw contents of a file from the authenticated account's sandbox GitHub repository. Resolves the github_repo from the [account's snapshot](/api-reference/sandboxes/list), then fetches the file at the specified path from the repository's main branch. Authentication is handled via the x-api-key header or Authorization Bearer token.
# List Sandboxes
Source: https://developers.recoupable.com/api-reference/sandboxes/list
/api-reference/openapi/content.json GET /api/sandboxes
List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Pass account_id to retrieve sandboxes for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.
# Setup Sandbox
Source: https://developers.recoupable.com/api-reference/sandboxes/setup
/api-reference/openapi/content.json POST /api/sandboxes/setup
Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.
# Update Snapshot
Source: https://developers.recoupable.com/api-reference/sandboxes/snapshot
/api-reference/openapi/content.json PATCH /api/sandboxes
Set a custom snapshot ID for an account. By default, updates the key owner's account. Pass account_id to target a specific account the API key has access to. This allows accounts to use a specific sandbox snapshot when creating new sandboxes, enabling reproducible environments with pre-configured tools, dependencies, and files.
# Upload Files
Source: https://developers.recoupable.com/api-reference/sandboxes/upload
/api-reference/openapi/content.json POST /api/sandboxes/files
Upload one or more files to the authenticated account's sandbox GitHub repository. Accepts an array of file URLs and commits each file to the specified directory path within the repository. Supports submodule resolution — if the target path falls within a git submodule, the file is committed to the submodule's repository. Authentication is handled via the x-api-key header or Authorization Bearer token.
# Social Scrape
Source: https://developers.recoupable.com/api-reference/social/scrape
/api-reference/openapi/social.json POST /api/socials/{id}/scrape
Trigger a social profile scraping job for a given social profile. Use the [Get Artist Socials](/api-reference/artists/socials) endpoint first to retrieve the social profile id values. The response returns Apify run metadata for polling status and retrieving results via the [Apify Scraper Results API](/api-reference/apify/scraper).
# Analyze Songs
Source: https://developers.recoupable.com/api-reference/songs/analyze
/api-reference/openapi/releases.json POST /api/songs/analyze
Analyze music using a state-of-the-art Audio Language Model that listens directly to the audio waveform. Unlike text-based AI, this model processes the actual sound — identifying harmony, structure, timbre, lyrics, and cultural context through deep music understanding. Supports audio up to 20 minutes (MP3, WAV, FLAC). Two modes: (1) **Presets** — pass a `preset` name like `catalog_metadata`, `mood_tags`, or `full_report` for structured, optimized output. (2) **Custom prompt** — pass a `prompt` for free-form questions. The `full_report` preset runs all 13 presets in parallel and returns a comprehensive music intelligence report. Use `GET /api/songs/analyze/presets` to list available presets.
# List Analyze Presets
Source: https://developers.recoupable.com/api-reference/songs/analyze-presets
/api-reference/openapi/releases.json GET /api/songs/analyze/presets
Lists all available music analysis presets. Each preset is a curated prompt with optimized generation parameters for a specific use case (e.g. catalog metadata enrichment, sync licensing analysis, audience profiling). Requires authentication via API key or Bearer token.
# Get Catalog Songs
Source: https://developers.recoupable.com/api-reference/songs/catalog-songs
get /api/catalogs/songs
Retrieve songs within a specific catalog with pagination support. This endpoint joins catalog_songs with songs, song_artists, and accounts to provide comprehensive song information for a given catalog.
This endpoint supports pagination. The Catalog Songs API also supports POST for adding songs and DELETE for removing songs. See the [Add Catalog Songs](/api-reference/songs/catalog-songs-add) and [Remove Catalog Songs](/api-reference/songs/catalog-songs-delete) endpoints.
# Add Catalog Songs
Source: https://developers.recoupable.com/api-reference/songs/catalog-songs-add
post /api/catalogs/songs
Batch add songs to a catalog by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.
For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.
# Remove Catalog Songs
Source: https://developers.recoupable.com/api-reference/songs/catalog-songs-delete
delete /api/catalogs/songs
Batch remove songs from a catalog by ISRC. Deletes the relationship in catalog_songs for each catalog_id and ISRC pair.
This endpoint removes the relationship in `catalog_songs` for each `catalog_id` and ISRC pair. The song data itself is not deleted.
# Get Catalogs
Source: https://developers.recoupable.com/api-reference/songs/catalogs
/api-reference/openapi/releases.json GET /api/accounts/{id}/catalogs
Retrieve catalogs associated with a specific account. The endpoint joins account_catalogs with catalogs to return catalog metadata for the specified account.
# Create Songs
Source: https://developers.recoupable.com/api-reference/songs/create
post /api/songs
Bulk create or fetch songs by ISRC. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.
This endpoint performs bulk create/fetch operations. For each song, the API attempts to look up metadata via internal search. If no data is found, optional fallback fields (name, album, notes, artists) are used.
# Get Songs
Source: https://developers.recoupable.com/api-reference/songs/songs
get /api/songs
Retrieve songs from the database with optional filtering by ISRC (International Standard Recording Code) or artist account. This endpoint joins the songs table with song_artists and accounts tables to provide comprehensive song information.
The Songs API also supports POST requests for bulk create/fetch operations. See the [Create Songs](/api-reference/songs/create) endpoint.
# Get Album
Source: https://developers.recoupable.com/api-reference/spotify/album
/api-reference/openapi/social.json GET /api/spotify/album
Get Spotify catalog information for a single album.
# Get Artist
Source: https://developers.recoupable.com/api-reference/spotify/artist
/api-reference/openapi/social.json GET /api/spotify/artist/
Get Spotify catalog information for a single artist identified by their unique Spotify ID.
# Get Artist Albums
Source: https://developers.recoupable.com/api-reference/spotify/artist-albums
/api-reference/openapi/social.json GET /api/spotify/artist/albums
Get Spotify catalog information about an artist's albums.
# Get Artist Top Tracks
Source: https://developers.recoupable.com/api-reference/spotify/artist-top-tracks
/api-reference/openapi/social.json GET /api/spotify/artist/topTracks
Get an artist's top tracks by country.
# Search
Source: https://developers.recoupable.com/api-reference/spotify/search
/api-reference/openapi/social.json GET /api/spotify/search
Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.
# Create Subscription Session
Source: https://developers.recoupable.com/api-reference/subscriptions/sessions-create
/api-reference/openapi/accounts.json POST /api/subscriptions/sessions
Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. The session is pre-configured with a 30-day trial period.
# Create Task
Source: https://developers.recoupable.com/api-reference/tasks/create
/api-reference/openapi/releases.json POST /api/tasks
Create a new scheduled task that runs a prompt against an artist on a recurring cron schedule. The response matches the [GET endpoint](/api-reference/tasks/get) (a `TasksResponse` with the created task in the `tasks` array).
# Delete Task
Source: https://developers.recoupable.com/api-reference/tasks/delete
/api-reference/openapi/releases.json DELETE /api/tasks
Delete an existing scheduled task by `id`. Returns only the delete operation status.
# Get Tasks
Source: https://developers.recoupable.com/api-reference/tasks/get
/api-reference/openapi/releases.json GET /api/tasks
Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.
# Get Task Runs
Source: https://developers.recoupable.com/api-reference/tasks/runs
/api-reference/openapi/releases.json GET /api/tasks/runs
Returns task runs for the authenticated account. When `runId` is provided, the response contains that single run (`runs` length 1) or 404 if not found. When `runId` is omitted, returns recent runs filtered by account context (default authenticated account, or `account_id` override when authorized).
# Update Task
Source: https://developers.recoupable.com/api-reference/tasks/update
/api-reference/openapi/releases.json PATCH /api/tasks
Update an existing scheduled task. Only the id field is required; any additional fields you include will be updated on the task. The response shape matches the GET endpoint (an array containing the updated task).
# Transcribe Audio
Source: https://developers.recoupable.com/api-reference/transcribe/audio
/api-reference/openapi/content.json POST /api/transcribe
Transcribe audio files using OpenAI Whisper. The API saves both the original audio file and the generated markdown transcript to the customer's files in Supabase Storage.
# Create Workspace
Source: https://developers.recoupable.com/api-reference/workspaces/create
/api-reference/openapi/accounts.json POST /api/workspaces
Create a new workspace account. Workspaces can optionally be linked to an organization.
# Authentication
Source: https://developers.recoupable.com/authentication
How authentication works in the Recoup API — API keys, access tokens, and organization access control.
## Overview
Every request to the Recoup API must be authenticated using exactly one of two mechanisms:
| Method | Header | Use case |
| ------------ | ------------------------------- | ------------------------------------- |
| API Key | `x-api-key` | Server-to-server integrations |
| Access Token | `Authorization: Bearer ` | Frontend apps authenticated via Privy |
Providing both headers in the same request will result in a `401` error.
Agent onboarding endpoints (`POST /api/agents/signup` and `POST /api/agents/verify`) are **unauthenticated** — they exist so agents can obtain their first API key. See the [Agents guide](/agents) for details.
***
## API Keys
API keys are the primary way to authenticate programmatic access to the Recoup API. All API keys are **personal keys** — they are always tied to the account that created them.
### Creating an API Key
1. Navigate to [chat.recoupable.com/keys](https://chat.recoupable.com/keys)
2. Enter a descriptive name (e.g. `"Production Server"`)
3. Click **Create API Key**
Copy your API key immediately — it is only shown once. Keys are stored as a secure HMAC-SHA256 hash and cannot be retrieved after creation.
### Using an API Key
Pass your key in the `x-api-key` header:
```bash theme={null}
curl -X GET "https://recoup-api.vercel.app/api/tasks" \
-H "x-api-key: YOUR_API_KEY"
```
### Access to Organizations
If your account belongs to one or more organizations, your API key can access data across those organizations by passing an `account_id` parameter on supported endpoints. This lets you filter to any account within an organization your key has access to.
* **No org membership** — the key can only access its own account's data
* **Org member** — the key can pass `account_id` to filter to any account within that organization
Org membership is determined by the account's [organizations](/api-reference/organizations/list). An account gains access to an org when it is added as a member.
***
## Access Tokens (Privy)
If you're building a frontend application that authenticates users via [Privy](https://privy.io), you can pass the user's Privy JWT as a Bearer token instead of an API key.
```bash theme={null}
curl -X GET "https://recoup-api.vercel.app/api/tasks" \
-H "Authorization: Bearer YOUR_PRIVY_JWT"
```
The API validates the token against Privy, extracts the user's email, and resolves it to the corresponding Recoup account. Bearer tokens always authenticate as a personal account — they cannot act on behalf of an organization.
***
## How We Verify Access on API Calls
Every authenticated request goes through `validateAuthContext`, which enforces the following access rules:
### API Key or Bearer Token
By default, requests access the key owner's own account. When `account_id` is provided:
```
Request includes account_id override?
├── Same as key owner → Allowed (self-access)
├── Key owner is a member of an org that contains account_id → Allowed
└── No matching org membership → 403 Forbidden
```
Membership is verified by checking the key owner's [organizations](/api-reference/organizations/list) for a record linking the account to the target account's organization.
The Recoup internal admin organization has universal access to all accounts.
### Organization Access via `organization_id`
Some endpoints accept an `organization_id` parameter. When provided, the API additionally validates that the authenticated account is either:
* A **member** of the organization, or
* The **organization account itself**
***
## Error Responses
| Status | Cause |
| ------ | -------------------------------------------------------------------------------------------- |
| `401` | Missing or invalid credentials, or both `x-api-key` and `Authorization` headers provided |
| `403` | Valid credentials but insufficient access to the requested `account_id` or `organization_id` |
***
## Security Notes
* API keys are **never stored in plaintext** — only an HMAC-SHA256 hash (keyed with your project secret) is persisted in the database
* **Never include `account_id` in your API key creation request** — the account is always derived from your authenticated credentials
* Rotate keys immediately if compromised via the [API Keys Management Page](https://chat.recoupable.com/keys)
# CLI
Source: https://developers.recoupable.com/cli
Install the Recoup CLI and interact with the platform from your terminal.
The Recoup CLI (`@recoupable/cli`) wraps the Recoup API for terminal-first workflows. It's available as a global npm package and comes pre-installed in sandbox environments.
**The CLI is in beta.** The commands listed below are what's shipped today (v0.1.13). For research workflows and most content operations, call the [REST API](/api-reference) directly — the CLI is gradually catching up.
**Agents:** if a command isn't listed below, don't retry — fall back to the corresponding REST endpoint linked under each command.
## Install
```bash theme={null}
npm install -g @recoupable/cli
```
## Authenticate
Set your API key as an environment variable:
```bash theme={null}
export RECOUP_API_KEY=your-api-key
```
Verify it works:
```bash theme={null}
recoup whoami
```
Get an API key from the [API Keys page](https://chat.recoupable.com/keys) or use the [agent signup](/agents) for instant key generation.
## Configuration
| Variable | Required | Default | Description |
| ---------------- | -------- | ------------------------------- | --------------------- |
| `RECOUP_API_KEY` | Yes | — | Your Recoup API key |
| `RECOUP_API_URL` | No | `https://recoup-api.vercel.app` | API base URL override |
All commands support `--json` for machine-readable output and `--help` for usage info.
***
## Commands
### whoami
Show the authenticated account. See [`GET /api/accounts/id`](/api-reference/accounts/id).
```bash theme={null}
recoup whoami
recoup whoami --json
```
### orgs
List organizations. See [`GET /api/organizations`](/api-reference/organizations/list).
```bash theme={null}
recoup orgs list
recoup orgs list --account
```
### artists
List artists. See [`GET /api/artists`](/api-reference/artists/list).
```bash theme={null}
recoup artists list
recoup artists list --org
recoup artists list --account
```
### notifications
Send a notification email to the authenticated account. See [`POST /api/notifications`](/api-reference/notifications/create).
```bash theme={null}
recoup notifications --subject "Pulse Report" --text "Here's your weekly summary."
recoup notifications --subject "Update" --html "Report
Details here.
"
```
| Flag | Required | Description |
| ----------------------- | -------- | ---------------------------------------------- |
| `--subject ` | Yes | Email subject line |
| `--text ` | No | Plain text or Markdown body |
| `--html ` | No | Raw HTML body (takes precedence over `--text`) |
| `--cc ` | No | CC recipient (repeatable) |
| `--room-id ` | No | Room ID for a chat link in the email footer |
| `--account ` | No | Send to a specific account (org keys only) |
### chats
Manage chats. See [`GET /api/chats`](/api-reference/chat/chats) and [`POST /api/chats`](/api-reference/chat/create).
```bash theme={null}
recoup chats list
recoup chats create --name "My Topic"
recoup chats create --name "My Topic" --artist
```
### sandboxes
Manage sandboxes. See [`GET /api/sandboxes`](/api-reference/sandboxes/list) and [`POST /api/sandboxes`](/api-reference/sandboxes/create).
```bash theme={null}
recoup sandboxes list
recoup sandboxes create
recoup sandboxes create --command "ls -la"
```
### tasks
Check background task status. See [`GET /api/tasks/runs`](/api-reference/tasks/runs).
```bash theme={null}
recoup tasks status --run
```
### songs
Run AI music analysis. See [`POST /api/songs/analyze`](/api-reference/songs/analyze) and [`GET /api/songs/analyze/presets`](/api-reference/songs/analyze-presets).
```bash theme={null}
recoup songs presets
recoup songs analyze --preset catalog_metadata --audio https://example.com/track.mp3
recoup songs analyze --prompt "Describe the production style" --audio https://example.com/track.mp3
```
One of `--preset` or `--prompt` is required. The other flags are optional.
| Flag | Required | Description |
| ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--preset ` | Conditional | Curated analysis preset. Required when `--prompt` is omitted. |
| `--prompt ` | Conditional | Custom text prompt. Required when `--preset` is omitted. |
| `--audio ` | No | Public URL to the audio file (MP3, WAV, FLAC). Some presets analyze the audio file; others (like `catalog_metadata`) work from metadata alone. |
| `--max-tokens ` | No | Max tokens to generate (default 512). |
***
## content
Content creation pipeline — generate AI-powered social videos for artists.
### List templates
```bash theme={null}
recoup content templates
```
### Validate an artist
Check that an artist has the required assets before creating content. See [`GET /api/content/validate`](/api-reference/content/validate).
```bash theme={null}
recoup content validate --artist
```
### Estimate cost
Preview estimated cost and duration before kicking off the pipeline. See [`POST /api/content/estimate`](/api-reference/content/estimate).
```bash theme={null}
recoup content estimate --artist
recoup content estimate --artist --template
```
### Create content
Run the full content-creation pipeline for an artist. See [`POST /api/content/create`](/api-reference/content/create).
```bash theme={null}
recoup content create --artist
recoup content create --artist --template --lipsync --upscale
```
| Flag | Required | Description |
| ---------------------- | -------- | -------------------------------- |
| `--artist ` | Yes | Artist account ID |
| `--template ` | No | Template name (default: random) |
| `--lipsync` | No | Enable lipsync mode |
| `--upscale` | No | Enable upscaling |
| `--caption-length ` | No | Max caption length in characters |
For finer-grained control (individual image, video, caption, transcription, edit, upscale, or analyze operations), call the [content REST endpoints](/api-reference/content/generate-image) directly. Those primitives aren't yet exposed as individual CLI subcommands.
# Content
Source: https://developers.recoupable.com/content-agent
Generate images, videos, captions, and social-ready content using AI-powered primitives
## Overview
Recoup's content API gives you seven independent primitives for generating and editing visual content. Each primitive does one thing well. You orchestrate them.
**Every primitive works without a template.** Pass your own prompt, reference images, and parameters directly. Templates are optional shortcuts — opinionated creative recipes that pre-fill parameters for a specific look.
## Primitives
| Primitive | Endpoint | What it does |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Generate Image | [POST /api/content/image](/api-reference/content/generate-image) | Create an image from a text prompt, optionally with a reference image for face/style |
| Generate Video | [POST /api/content/video](/api-reference/content/generate-video) | Create a video — 6 modes: prompt, animate, reference, extend, first-last, lipsync |
| Generate Caption | [POST /api/content/caption](/api-reference/content/generate-caption) | Generate on-screen text for social media videos |
| Transcribe Audio | [POST /api/content/transcribe](/api-reference/content/transcribe-audio) | Transcribe audio to timestamped lyrics/text |
| Edit Content | [PATCH /api/content](/api-reference/content/edit) | Trim, crop, resize, overlay text, or add audio — one processing pass |
| Upscale | [POST /api/content/upscale](/api-reference/content/upscale) | Upscale image or video resolution (up to 4x) |
| Analyze Video | [POST /api/content/analyze](/api-reference/content/analyze-video) | AI video analysis — describe scenes, check quality, evaluate content |
There is also [POST /api/content/create](/api-reference/content/create) which runs the full pipeline in one call — use it when you want a video without creative control over each step.
## How It Works
### Without a template (malleable mode)
Pass your own parameters directly to any primitive. Maximum creative control.
```bash theme={null}
# Generate an image with your own prompt
curl -X POST https://recoup-api.vercel.app/api/content/image \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "A moody portrait in a dimly lit room, front-facing phone camera"}'
# Generate a video from that image
curl -X POST https://recoup-api.vercel.app/api/content/video \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"image_url": "IMAGE_URL_FROM_ABOVE", "prompt": "subtle breathing motion, nearly still"}'
```
### With a template (shortcut mode)
Pass a template ID and the primitive fills in prompts, reference images, and style rules automatically. You can still override any parameter.
```bash theme={null}
# Same image, but the template provides the prompt and reference images
curl -X POST https://recoup-api.vercel.app/api/content/image \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"template": "artist-caption-bedroom", "reference_image_url": "YOUR_FACE_IMAGE"}'
```
Use [GET /api/content/templates](/api-reference/content/templates) to see available templates with descriptions.
## Templates
A template is a complete creative recipe — it defines what a piece of content looks like across every primitive:
* **Image config**: prompt, reference images, style rules (camera, lighting, composition)
* **Video config**: mood variations, movement descriptions
* **Caption config**: tone, formatting rules, example captions
* **Edit config**: crop ratio, text overlay style, audio mixing
Templates are optional. They save time by pre-filling parameters with curated defaults. When you see customers repeatedly creating the same kind of content, that pattern becomes a template.
### Override priority
When using a template, your explicit parameters always win:
1. **Your params** — highest priority. What you pass overrides everything.
2. **Artist context** — if the artist has a style guide, it personalizes the template.
3. **Template defaults** — lowest priority. The recipe's built-in values.
## Video Modes
The video primitive supports 6 generation modes:
| Mode | What it does | Required inputs |
| ------------ | ---------------------------------------------- | -------------------------------------- |
| `prompt` | Create from text description | `prompt` |
| `animate` | Animate a still image | `image_url`, `prompt` |
| `reference` | Use image as style reference (not first frame) | `image_url`, `prompt` |
| `extend` | Continue an existing video | `video_url`, `prompt` |
| `first-last` | Transition between two images | `image_url`, `end_image_url`, `prompt` |
| `lipsync` | Sync face to audio | `image_url`, `audio_url` |
Set `mode` explicitly, or omit it and the API infers the mode from the inputs you provide.
## Iteration
Each primitive is independent. Redo any step without rerunning the whole pipeline:
* Bad image? Regenerate with a different prompt or reference
* Caption too long? Regenerate with `length: "short"`
* Video glitchy? Analyze it, then regenerate with adjusted params
* Clip too short? Use `extend` mode to continue it
* Low quality? Upscale the image or video
* Everything good but wrong caption? Just re-run the edit step
## Content Agent (Slack Bot)
The **Recoup Content Agent** is a Slack bot that generates social-ready artist videos on @mention. It plugs into the content creation pipeline and delivers results directly in your Slack thread.
### @Mention Syntax
```
@RecoupContentAgent [template] [batch=N] [lipsync]
```
| Parameter | Required | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `artist_account_id` | Yes | UUID of the artist account |
| `template` | No | Content template name. Optional — when omitted, the pipeline runs with default settings. See [GET /api/content/templates](/api-reference/content/templates) for options. |
| `batch=N` | No | Number of videos to generate (1-30, default 1) |
| `lipsync` | No | Enable lipsync mode (audio baked into video) |
### Examples
**Basic — single video with default template:**
```
@RecoupContentAgent abc-123-uuid
```
**Custom template:**
```
@RecoupContentAgent abc-123-uuid artist-caption-bedroom
```
**Batch with lipsync:**
```
@RecoupContentAgent abc-123-uuid batch=3 lipsync
```
### Architecture
| Component | Location | Purpose |
| ----------------- | ---------------------------------- | ------------------------------------------------- |
| Slack webhook | `POST /api/content-agent/slack` | Receives @mention events |
| Callback endpoint | `POST /api/content-agent/callback` | Receives polling results |
| Bot singleton | `lib/content-agent/bot.ts` | Chat SDK with Slack adapter + Redis state |
| Mention handler | `lib/content-agent/handlers/` | Parses args, validates artist, triggers pipeline |
| Poll task | `poll-content-run` (Trigger.dev) | Monitors content runs, posts results via callback |
### Data Flow
1. **Slack event** → `POST /api/content-agent/slack` handles the webhook
2. **Mention handler** parses the command, calls [`GET /api/content/validate`](/api-reference/content/validate) to check artist readiness
3. **Content creation** triggered via [`POST /api/content/create`](/api-reference/content/create) — returns `runIds`
4. **Poll task** (`poll-content-run`) monitors the Trigger.dev runs every 30 seconds (up to 30 minutes)
5. **Callback** → [`POST /api/content-agent/callback`](/api-reference/content-agent/callback) receives results and posts video URLs back to the Slack thread
### Setup
#### 1. Create a Slack App
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
2. Under **OAuth & Permissions**, add bot scopes:
* `chat:write` — post messages
* `app_mentions:read` — receive @mention events
3. Under **Event Subscriptions**:
* Enable events
* Set the request URL to `https://recoup-api.vercel.app/api/content-agent/slack`
* Subscribe to `app_mention` bot event
4. Install the app to your workspace
#### 2. Configure Environment Variables
| Variable | Where | Description |
| ------------------------------- | ------------------- | -------------------------------------------------------------------- |
| `SLACK_CONTENT_BOT_TOKEN` | API (Vercel) | Bot OAuth token (`xoxb-...`) from Slack app |
| `SLACK_CONTENT_SIGNING_SECRET` | API (Vercel) | Signing secret from Slack app **Basic Information** |
| `CONTENT_AGENT_CALLBACK_SECRET` | API + Tasks | Shared secret for callback authentication (generate a random string) |
| `RECOUP_API_KEY` | API + Tasks | Recoup API key for authenticating pipeline requests |
| `RECOUP_API_BASE_URL` | Tasks (Trigger.dev) | API base URL (e.g., `https://recoup-api.vercel.app`) |
#### 3. Verify
Mention the bot in any Slack channel where it's been added:
```
@RecoupContentAgent
```
You should see:
1. An immediate acknowledgment message
2. A video URL reply in the thread after \~5-10 minutes
### Troubleshooting
| Issue | Cause | Fix |
| ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
| No response from bot | Event subscription URL not configured | Check Slack app Event Subscriptions |
| "Artist not found" | Invalid `artist_account_id` | Verify the UUID exists in the platform |
| "No GitHub repository found" | Artist missing repo config | Ensure the artist account has a linked GitHub repo |
| Timeout after 30 min | Pipeline took too long | Check Trigger.dev dashboard for the failed run |
| "Unsupported template" | Invalid template name | Use [`GET /api/content/templates`](/api-reference/content/templates) to list available templates |
# Recoup API Documentation
Source: https://developers.recoupable.com/index
Use the Recoup API to build your record label. Access research, content creation, chat, artist analytics, social media, and platform management endpoints.
# Welcome to the Recoup API
Use the Recoup API to build your record label. Generate content, Access artist analytics, Manage catalogs, Team chats, and task automation to power your record labels.
## Quickest start — one curl call
Get a working API key in a single unauthenticated request. No dashboard, no browser, no human in the loop.
```bash theme={null}
export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-H "Content-Type: application/json" \
-d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
```
`$RECOUP_API_KEY` is now ready to pass in the `x-api-key` header on any request. See the [Agents guide](/agents) for the full signup and verification flow.
## What is Recoup?
Recoup is an AI agent platform for smarter song rollouts, unforgettable fan experiences, and lasting artist growth. Empowering music executives with actionable insights and next-gen tools.
This is where record labels, musicians, and managers start to build on Recoup AI technology like chat, tasks, agents, and more.
## Base URL
All API requests should be made to:
```bash theme={null}
https://recoup-api.vercel.app/api
```
## Authentication
Most API endpoints are authenticated using an API key passed in the `x-api-key` header. The only exceptions are the [agent onboarding](/agents) endpoints — [`POST /api/agents/signup`](/api-reference/agents/signup) and [`POST /api/agents/verify`](/api-reference/agents/verify) — which are intentionally unauthenticated so agents can obtain their first API key.
1. Navigate to the [API Keys Management Page](https://chat.recoupable.com/keys)
2. Sign in with your account
3. Create a new API key and copy it immediately (it's only shown once)
```bash theme={null}
curl -X GET "https://recoup-api.vercel.app/api/artists?accountId=YOUR_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY"
```
Keep your API key secure. Do not share it publicly or commit it to version control.
## Get Started
Get an API key in one curl call. The fastest path for AI agents — no dashboard required.
Get your API key and make your first request in minutes.
Install and use the Recoup CLI to interact with the platform from your terminal.
Connect Recoup to AI assistants via the Model Context Protocol.
## API Sections
The API is organized into six main sections. Use these links to jump to the right area.
30 endpoints for artist research: search, lookup, profile, metrics, audience, cities, similar artists, playlists, albums, tracks, career history, insights, genres, festivals, web presence, and more.
Generate images, videos, and captions. Transcribe audio, edit content, upscale media, analyze videos, manage templates, and estimate costs.
Conversations with artist context. Create, stream, and generate messages. Copy messages, delete trailing messages, and manage chat history.
Spotify, Instagram, X (Twitter), and generic social scraping. Search artists, scrape profiles and comments, track trends, and manage OAuth connectors.
Songs, catalogs, and task management. Analyze songs, manage catalog collections, and schedule recurring tasks with cron-based automation.
Accounts, organizations, workspaces, subscriptions, pulses, notifications, sandboxes, and admin tools.
## Agents
Content creation agent accessible via Slack. Generates images, videos, and captions for artists automatically.
API key authentication, account-scoped access, and organization-level permissions.
## Quick Reference for LLMs
If you are an LLM navigating these docs, here is a summary of the endpoint structure:
* **`/api/artists/*`** — Artist management (list, create, socials, socials-scrape, profile)
* **`/api/research/*`** — Artist research (search, lookup, profile, metrics, audience, cities, similar, urls, instagram-posts, playlists, albums, track, tracks, career, insights, genres, festivals, web, deep, people, extract, enrich, milestones, venues, rank, charts, radio, discover, curator, playlist)
* **`/api/content/*`** — Content creation (create, generate-image, generate-video, generate-caption, transcribe-audio, edit, upscale, analyze-video, templates, validate, estimate)
* **`/api/chat/*`** — Chat (chats, artist, messages, messages-copy, messages-trailing-delete, create, update, delete, generate, stream, compact)
* **`/api/songs/*`** — Songs and catalogs (songs, create, analyze, analyze-presets, catalogs, catalogs-create, catalogs-delete, catalog-songs, catalog-songs-add, catalog-songs-delete)
* **`/api/tasks/*`** — Task automation (get, create, update, delete, runs)
* **`/api/spotify/*`** — Spotify (search, artist, artist-albums, artist-top-tracks, album)
* **`/api/instagram/*`** — Instagram (comments, profiles)
* **`/api/x/*`** — X/Twitter (search, trends)
* **`/api/connectors/*`** — OAuth connectors (list, authorize, disconnect)
* **`/api/accounts/*`** — Accounts (get, id, create, update, add-artist)
* **`/api/organizations/*`** — Organizations (list, create, add-artist)
* **`/api/sandboxes/*`** — Sandboxes (list, create, snapshot, delete, setup, file, upload)
* **`/api/content-agent/*`** — Content agent webhooks (webhook, callback)
* **`/api/agents/*`** — Agent onboarding (signup, verify) — no auth required
Base URL: `https://recoup-api.vercel.app/api`
[OpenAPI Specification](https://github.com/sweetmantech/docs/blob/main/api-reference/openapi.json)
## Need Help?
Reach out to our team at [agent@recoupable.com](mailto:agent@recoupable.com) for assistance with the Recoup API.
# MCP
Source: https://developers.recoupable.com/mcp
Connect AI agents to the Recoup platform using the Model Context Protocol (MCP) server.
The Recoup API exposes an [MCP](https://modelcontextprotocol.io/) server that AI agents can connect to for tool use. The server is available at:
```
https://recoup-api.vercel.app/mcp
```
## Authentication
All MCP tools require an API key. Pass it as a Bearer token in the `Authorization` header when connecting to the MCP server.
You can get a key from the [API Keys page](https://chat.recoupable.com/keys).
## Tools
### prompt\_sandbox
Send a prompt to OpenClaw running in a persistent per-account sandbox. The sandbox is reused across calls — if one is already running it picks up where you left off, otherwise a new one is created from the account's latest snapshot.
Returns raw `stdout` and `stderr` from the command. The sandbox stays alive after each prompt for follow-up interactions.
**Input schema:**
| Parameter | Type | Required | Description |
| --------- | -------- | -------- | ---------------------------------------------- |
| `prompt` | `string` | Yes | The prompt to send to OpenClaw in the sandbox. |
**Response fields:**
| Field | Type | Description |
| ----------- | --------- | --------------------------------------------------------------------------- |
| `sandboxId` | `string` | The Vercel Sandbox ID. |
| `stdout` | `string` | Standard output from the command. |
| `stderr` | `string` | Standard error from the command. |
| `exitCode` | `number` | Process exit code (`0` = success). |
| `created` | `boolean` | `true` if a new sandbox was created, `false` if an existing one was reused. |
**Example usage (TypeScript with MCP SDK):**
```typescript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const transport = new StreamableHTTPClientTransport(
new URL("https://recoup-api.vercel.app/mcp"),
{ requestInit: { headers: { Authorization: `Bearer ${RECOUP_API_KEY}` } } },
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
name: "prompt_sandbox",
arguments: { prompt: "list all files in the orgs directory" },
});
console.log(result.content);
```
### run\_sandbox\_command
Create a sandbox and run a shell command or OpenClaw prompt in it. Unlike `prompt_sandbox`, this creates a **new sandbox each call** and runs the command asynchronously via a background task. Returns a sandbox ID and run ID to track progress.
See [`POST /api/sandboxes`](/api-reference/sandboxes/create) for the equivalent REST endpoint.
**Input schema:**
| Parameter | Type | Required | Description |
| ------------ | ---------- | -------- | --------------------------------------------------- |
| `command` | `string` | No | Shell command to run. Cannot be used with `prompt`. |
| `args` | `string[]` | No | Arguments for the command. |
| `cwd` | `string` | No | Working directory for the command. |
| `prompt` | `string` | No | OpenClaw prompt. Cannot be used with `command`. |
| `account_id` | `string` | No | Target a specific account (org API keys only). |
# Quickstart
Source: https://developers.recoupable.com/quickstart
Get a Recoup API key in one call and make your first request — no browser, no dashboard.
## Quickest start
Sign up your agent and get an API key in a single API call — no dashboard, no browser, no human in the loop. This one-liner signs up a fresh `agent+` address and exports the returned key to `$RECOUP_API_KEY`:
```bash theme={null}
export RECOUP_API_KEY=$(curl -s -X POST "https://recoup-api.vercel.app/api/agents/signup" \
-H "Content-Type: application/json" \
-d '{"email": "agent+'$(date +%s)-$RANDOM'@recoupable.com"}' | jq -r .api_key)
```
Verify it worked:
```bash theme={null}
curl -H "x-api-key: $RECOUP_API_KEY" https://recoup-api.vercel.app/api/accounts/id
```
The `agent+{timestamp}@recoupable.com` shape is the fastest path for agents — it guarantees a fresh `agent+` address and returns an API key instantly without email verification.
For the full signup + email-verification flow, see the [Agents guide](/agents).
## Base URL
All API requests should be made to:
```bash theme={null}
https://recoup-api.vercel.app/api
```
## Your First Request
Once you have an API key, include it in the `x-api-key` header on every request. Here's a simple call that retrieves your scheduled tasks:
```bash cURL theme={null}
curl -X GET "https://recoup-api.vercel.app/api/tasks" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY"
```
```python Python theme={null}
import requests
headers = {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
}
response = requests.get(
"https://recoup-api.vercel.app/api/tasks",
headers=headers
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://recoup-api.vercel.app/api/tasks", {
headers: {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
},
});
const data = await response.json();
console.log(data);
```
```typescript TypeScript theme={null}
interface Task {
id: string;
title: string;
prompt: string;
schedule: string;
account_id: string;
artist_account_id: string;
enabled: boolean;
}
interface TasksResponse {
status: "success" | "error";
tasks: Task[];
}
const response = await fetch("https://recoup-api.vercel.app/api/tasks", {
headers: {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
},
});
const data: TasksResponse = await response.json();
console.log(data.tasks);
```
**Example Response:**
```json theme={null}
{
"status": "success",
"tasks": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Daily Fan Report",
"prompt": "Generate a summary of new fans from the past 24 hours",
"schedule": "0 9 * * *",
"account_id": "123e4567-e89b-12d3-a456-426614174000",
"artist_account_id": "987fcdeb-51a2-3b4c-d5e6-789012345678",
"enabled": true
}
]
}
```
For full documentation on the Tasks API including filtering options, see the [Tasks API Reference](/api-reference/tasks/get).
## Prefer the dashboard?
If you're a human building an integration, you can also create API keys from the web console instead of the signup endpoint:
1. Navigate to the [Recoup API Keys Management Page](https://chat.recoupable.com/keys)
2. Sign in with your account
3. Enter a descriptive name (e.g. "Production Server")
4. Click **Create API Key**
Copy and securely store your API key immediately — it will only be shown once.
## Next Steps
With your API key ready, you can now:
Fetch artist profiles and social accounts.
Access fan data across all connected social platforms.
Build AI-powered conversations with artist context.
Schedule and automate recurring tasks.
## Support
If you need help or have questions about the API, please contact our support team at [agent@recoupable.com](mailto:agent@recoupable.com).
# Create a New Artist
Source: https://developers.recoupable.com/workflows/create-artist
End-to-end workflow to create, research and enrich a new artist account in a single session.
This is the canonical recipe used internally by Recoup's chat agent. Follow it step-by-step to bring a new artist account up to "researched + enriched" parity from a sandbox or any external agent.
The chain is 8 sequential API calls. Long deterministic chains executed from prose memory tend to drop steps — the agent reads the doc once, runs a couple of calls, and forgets the rest. To prevent that from a sandbox, **drive the work from a checklist file**: scaffold the artist's `RECOUP.md` with one checkbox per step before any API call, then tick each box and persist captured values back to the frontmatter as you go. The file becomes the workflow state, and a fresh turn can resume by reading it.
## Prerequisites
* `$RECOUP_ACCESS_TOKEN` — Bearer token for `recoup-api.vercel.app`
* `$RECOUP_ORG_ID` — the org the artist should belong to (recommended in sandboxes)
* An artist name to create (e.g. `ARTIST_NAME="The Weeknd"`)
The flow has three phases, run from a single checklist file:
1. **Create + identify** — `POST /api/artists`, then find the canonical Spotify match
2. **Enrich** — `PATCH` the artist with image/label/socials, then run structured research (Chartmetric profile/career/playlists) plus a web search for narrative context and additional socials
3. **Synthesize + persist** — generate a knowledge-base report, save it (RECOUP.md tree or hosted URL), then optionally `PATCH` the `knowledges` array
## Step 0: Scaffold the workspace BEFORE any API call
Pick a slug, make the directory, and write the initial `RECOUP.md` template — frontmatter holds the values the chain captures (filled as you go); body holds the unchecked steps:
```bash theme={null}
ARTIST_SLUG=$(echo "$ARTIST_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\+/-/g; s/^-//; s/-$//')
ARTIST_DIR="artists/$ARTIST_SLUG"
mkdir -p "$ARTIST_DIR"
cat > "$ARTIST_DIR/RECOUP.md" <