# Bring your own key (BYOK) Source: https://tmoody1973-crate-web-34.mintlify.app/billing/byok Use your own Anthropic or OpenRouter API key for unlimited queries BYOK lets you connect your own Anthropic or OpenRouter API key to Digcrate. When a key is set, your queries use your key instead of the platform key — so you're not subject to monthly query limits. BYOK is useful if you're a heavy user who regularly hits your monthly quota, or if you want to use models that aren't available on the standard platform key. Your key is used directly for API calls to Anthropic or OpenRouter. Standard API costs from those providers apply to every query you run. Digcrate does not mark up these costs. ## Setting up your key Click **Settings** in the sidebar, then go to the **API Keys** tab. Paste your Anthropic key (starts with `sk-ant-...`) or your OpenRouter key into the corresponding field. Click **Save**. Digcrate will validate the key before saving it. If the key is invalid, you'll see an error and nothing will be stored. Once a key is connected, open the model picker in the chat input to choose a different model. BYOK unlocks all models available for your key type. Your key is encrypted at rest. Digcrate never logs or exposes it. ## Supported key types Connects to Claude models directly via the Anthropic API. Paste your key from [console.anthropic.com](https://console.anthropic.com). **Key format:** `sk-ant-...` Routes to any model OpenRouter supports, including Claude, GPT-4o, Gemini, Llama, DeepSeek, and Mistral. Paste your key from [openrouter.ai/keys](https://openrouter.ai/keys). **Key format:** `sk-or-...` ## Available models When an OpenRouter key is connected, you can select any of these models from the model picker: | Model | Provider | | ----------------- | -------------------------- | | Claude Sonnet 4.6 | Anthropic (via OpenRouter) | | GPT-4o | OpenAI | | Gemini 2.5 | Google | | Llama 4 | Meta | | DeepSeek R1 | DeepSeek | | Mistral Large | Mistral AI | With an Anthropic key, you can access Claude models directly without routing through OpenRouter. ## How query limits work with BYOK When a valid key is stored, Digcrate routes your agent queries through that key instead of the platform key. Your monthly query count from your plan is not decremented — you can run as many queries as your API key's rate limits allow. Your plan's other limits (saved sessions, custom skills, publishing, memory) still apply based on your subscription tier. ## Removing your key To disconnect a key, open **Settings → API Keys**, clear the field, and save. Digcrate will switch back to the platform key and your monthly quota will apply again. # Plans Source: https://tmoody1973-crate-web-34.mintlify.app/billing/plans Free, Pro, and Team plans for every type of music researcher Digcrate offers three plans. All plans include access to 20+ data sources, connected services (Spotify, Slack, Google Docs), and the full library of slash commands. Paid plans unlock higher query limits, publishing, cross-session memory, and more custom skills. ## Plan comparison | Feature | Free | Pro | Team | | --------------------------- | ---- | --------- | ------------ | | **Price** | \$0 | \$15/mo | \$25/mo | | **Agent queries/month** | 10 | 50 | 200 (pooled) | | **Saved sessions** | 5 | Unlimited | Unlimited | | **Custom skills** | 3 | 20 | 50 | | **Scheduled skills** | — | 3 | 10 | | **Publishing** (`/publish`) | — | Yes | Yes | | **Cross-session memory** | — | Yes | Yes | | **Influence caching** | — | Yes | Yes | | **Admin dashboard** | — | — | Yes | | **Shared org API keys** | — | — | Yes | ### Free Start researching without a credit card. You get 10 agent queries per month, 5 saved sessions, and up to 3 custom skills. All 20+ data sources are available, and you can connect Spotify, Slack, and Google Docs. ### Pro — \$15/mo The full Digcrate experience. 50 agent queries per month, unlimited sessions, and 20 custom skills. Pro also unlocks: * **Publishing** — use `/publish telegraph` or `/publish tumblr` to push your research to the web and `/published` to view everything you've shared * **Cross-session memory** — Digcrate remembers context across sessions (powered by Mem0) * **Influence caching** — influence maps are cached so repeat lookups are instant * **Scheduled skills** — run up to 3 custom skills on a schedule ### Team — \$25/mo Designed for radio stations, labels, and music organizations. 200 agent queries pooled across your domain, 50 custom skills, and everything in Pro, plus: * **Admin dashboard** — see usage across your organization * **Shared org keys** — set a single API key that all team members use * **Scheduled skills** — run up to 10 custom skills on a schedule Team plan accounts must use a work or organization email address. Free email providers (Gmail, Yahoo, Outlook, iCloud, etc.) are not eligible for Team plan creation. ## Rate limits All plans share the same per-minute rate limits regardless of monthly quota: | Limit | Value | | ------------------------ | ----- | | Agent queries per minute | 5 | | Chat messages per minute | 30 | These are soft limits that reset every 60 seconds. If you hit a rate limit, wait a moment and try again. ## Pro-only commands The following slash commands require a Pro or Team plan: * `/publish` — publish research to Telegraph or Tumblr * `/published` — list everything you've published Running either command on the Free plan will prompt you to upgrade. ## Managing your subscription Billing is handled by Stripe. To manage your subscription: 1. Open **Settings** in the sidebar 2. Go to the **Plan** tab 3. Click **Manage subscription** to open the Stripe billing portal From the billing portal you can: * Upgrade or downgrade your plan * Update your payment method * View past invoices * Cancel your subscription Cancellations take effect at the end of the current billing period. You keep Pro or Team access until then. ## BYOK — bring your own key If you have your own Anthropic or OpenRouter API key, you can connect it to bypass monthly query limits entirely. See [Bring your own key](/billing/byok). # /artist — Artist profile Source: https://tmoody1973-crate-web-34.mintlify.app/commands/artist Generate a full artist deep dive with discography, influences, media, and top tracks The `/artist` command researches an artist across MusicBrainz, Discogs, Last.fm, Genius, and YouTube, then renders the results as a single interactive `ArtistProfile` component with four tabbed views. ## Syntax ``` /artist [name] ``` | Parameter | Description | | --------- | ----------------------------------------- | | `name` | Artist name — any spelling or alias works | ## Example ``` /artist MF DOOM ``` ## What it produces The agent outputs an `ArtistProfile` component — a full-page interactive deep dive with the following tabs: | Tab | Content | | --------------- | -------------------------------------------------------------------------------- | | **Discography** | Playable albums and releases with cover art | | **Connections** | Influence and collaboration chips you can tap to explore further | | **Media** | YouTube videos (documentaries, interviews, live performances) and external links | | **Top tracks** | Most-streamed and most-researched tracks | ## Research steps The agent queries these sources in order: Fetches artist metadata, discography, and relationships (members, collaborators, labels). Retrieves releases, label history, credits, and collaborators. Pulls listener stats, genre tags, and similar artists. Fetches the artist bio and notable annotations. Searches for a documentary, interview, or live performance to embed in the Media tab. Resolves the artist image for the profile header. ## Related commands Trace an artist's musical connections through reviews and co-mentions Deep dive into a specific track from the artist's catalog Get a rich narrative on an album, era, or movement Build show prep around an artist's tracks After the `ArtistProfile` loads, use the **Influence Map** action button on the component to jump directly to `/influence` for that artist. # /influence — Influence map Source: https://tmoody1973-crate-web-34.mintlify.app/commands/influence Trace an artist's musical connections through reviews, collaborations, and co-mentions The `/influence` command maps an artist's musical connections by checking the influence cache, running discovery if needed, and rendering an `InfluenceChain` component — a narrative timeline with a hero banner, tabbed connection cards, and cited sources. ## Syntax ``` /influence [artist] ``` | Parameter | Description | | --------- | --------------------------------- | | `artist` | Artist name to map influences for | ## Example ``` /influence J Dilla ``` ## What it produces The agent outputs an `InfluenceChain` component with: * A hero banner for the subject artist * 6–12 connection cards sorted by weight (strongest connections first) * Tabs for each connection showing context, sonic elements, key works, and sources * Source citations with direct links from the research ## How connections are discovered The agent runs in three phases: Calls `lookup_influences` to check whether connections have been cached from a previous research session. If 5 or more connections are found, the agent skips to the enrich phase. Runs a Perplexity web search for `[artist] musical influences collaborations discography` to get a comprehensive overview in one call. If more signal is needed, searches review co-mentions — when two artists are mentioned together in a review, that co-occurrence is treated as an influence signal. Calls `research_influences_batch` with the top 3–5 connection names. This fires parallel Perplexity calls and returns all results in one response. Results are then saved back to the cache. ## Connection fields Each connection in the `InfluenceChain` includes: | Field | Description | | ---------------------- | -------------------------------------------------------------- | | `name` | Connected artist name | | `weight` | Connection strength (0–1), used for sort order | | `relationship` | `influenced by`, `collaborated with`, or `co_mention` | | `context` | Enriched paragraph or summary from research | | `pullQuote` | Direct quote if found (optional) | | `pullQuoteAttribution` | `Artist Name, Publication, Year` (optional) | | `sonicElements` | Array of sonic or stylistic qualities shared between artists | | `keyWorks` | Album-to-album reference showing the connection in the catalog | | `sources` | Array of `{ name, url, snippet, date }` from research | ## Direction convention Digcrate uses the Badillo-Goicoechea 2025 direction convention for edges in the influence graph: * `from` = **INFLUENCER**, `to` = **INFLUENCED** * If a review of artist B mentions artist A → edge points A → B * `influenced by` for directional influence * `collaborated with` for production or co-creation * `co_mention` for same-review co-occurrence without a clear directional signal Artist images are auto-fetched from Spotify by the `InfluenceChain` component. The agent does not need to look up artwork — passing image URLs is not required. ## Related commands Full artist profile including the Connections tab Narrative deep dive on an artist, genre, or movement Track-level research including credits and samples Pro users benefit from influence caching — previously discovered connections load instantly and skip the discovery phase entirely. # /news — Music news Source: https://tmoody1973-crate-web-34.mintlify.app/commands/news Generate daily music news segments from RSS feeds and web search The `/news` command generates a radio-ready daily music news segment pulled from RSS feeds and web search, scoped to the past 24–48 hours and formatted for a specific station's voice and audience. ## Syntax ``` /news [station] [count] ``` | Parameter | Required | Description | | --------- | -------- | ------------------------------------------------------------------ | | `station` | No | `88nine`, `hyfin`, or `rhythmlab` — sets the voice and music focus | | `count` | No | Number of stories to generate, 1–5 (default: 5) | ## Example ``` /news hyfin 3 ``` This generates 3 news stories written in HYFIN's voice — bold, culturally sharp, focused on hip-hop, neo-soul, and Afrobeats. ## Station voices Specifying a station shapes every story: the tone, the music focus, the angle, and the sources prioritized. | Station | Voice | Focus | | ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- | | `88nine` | Warm, eclectic, community-forward | Indie, alternative, world, electronic. Milwaukee music lover audience. | | `hyfin` | Bold, culturally sharp | Hip-hop, neo-soul, Afrobeats, cultural context. Young, culturally aware Milwaukee audience. | | `rhythmlab` | Curated, global perspective, deep knowledge | Global beats, electronic, jazz fusion. DJs, producers, crate diggers. | All stations prioritize Milwaukee local sources — milwaukeerecord.com, jsonline.com, urbanmilwaukee.com — for local angles. ## What it generates The command outputs a numbered segment formatted for on-air reading: ``` For [Day]: 1. [Story headline] — [2–3 sentence summary] [Source](url) 2. [Story headline] — [2–3 sentence summary] [Source](url) ... ``` Each story includes a direct link to the source. The agent only uses URLs returned by its search tools — it never fabricates or guesses source links. ## Research steps One broad search for `music news today [date]` to surface the latest stories. One call to music news RSS feeds to catch stories not picked up by web search. The agent picks the most compelling stories from the combined results — it does not fetch individual articles. Stories older than 3 days are discarded. The segment is written directly from search snippets and summaries. Additional tool calls only happen if a specific fact needs verification. The agent rejects any results older than 3 days. If search returns older articles, it re-runs the search with tighter date filters before writing the segment. ## Related commands Full show prep package including track context and talk breaks Narrative deep dive on any artist, album, or movement # /radio — Live radio Source: https://tmoody1973-crate-web-34.mintlify.app/commands/radio Search and stream any of 30,000+ radio stations directly in the workspace The `/radio` command searches the Radio Browser database of 30,000+ stations and starts streaming the best match in the Digcrate audio player. You can search by genre, station name, or pass a direct stream URL. ## Syntax ``` /radio [genre or station name] ``` ``` /radio [https://stream-url] ``` | Parameter | Description | | ----------------------- | ----------------------------------------------------------------- | | `genre or station name` | Any genre, vibe, or station name — the agent picks the best match | | `https://...` | A direct stream URL — starts playing immediately without a search | ## Examples Search by genre: ``` /radio jazz ``` Search by station name: ``` /radio KEXP ``` Play a direct URL: ``` /radio https://kexp.streamguys1.com/kexp160.mp3 ``` ## How it works If the input starts with `http://` or `https://`, the agent skips the search and plays the stream directly using `play_radio`. For a genre or station name, the agent calls `search_radio` with the query. Genre queries search by tag; station name queries search by name. The agent selects the highest-voted station with a working stream. If multiple strong matches exist, it shows the top 3–5 and asks which one to play. Calls `play_radio` with the station name or URL. The stream starts in the persistent audio player at the bottom of the workspace. The audio player persists across the workspace — you can keep a station playing while you research tracks, run show prep, or map influence chains. ## Related commands Generate show prep for the station you're streaming Pull daily music news for a specific station's voice # /prep — Show prep Source: https://tmoody1973-crate-web-34.mintlify.app/commands/show-prep Full radio show prep with track context, talk breaks, social copy, and interview prep The `/prep` command generates a complete radio show prep package for a given setlist. The agent researches each track, then outputs a `ShowPrepPackage` component with context cards, talk breaks, social copy, concert events, and — if a guest is listed — interview prep. ## Basic syntax ``` /prep [station]: [setlist] ``` Paste your setlist after the station name, one track per line in `Artist - Track` format. ## Stations | Station | Voice and focus | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **88Nine** | Warm, eclectic, community-forward. Indie, alternative, world, electronic, hip-hop. Audience: Milwaukee music lovers who value discovery. Vocabulary: discover, connect, community, eclectic, homegrown. | | **HYFIN** | Bold, culturally sharp, unapologetic. Urban alternative, neo-soul, progressive hip-hop, Afrobeats. Audience: young, culturally aware Milwaukee listeners invested in Black art and music. Vocabulary: culture, movement, lineage, vibration, frequency. | | **Rhythm Lab** | Curated, global perspective, deep knowledge. Global beats, electronic, jazz fusion, experimental, Afrobeats, dub. Audience: dedicated music heads, DJs, producers, crate diggers. Vocabulary: lineage, crate, connection, thread, sonic, palette. | ## Example ``` /prep HYFIN: Erykah Badu - On & On D'Angelo - Brown Sugar J Dilla - Won't Do Sade - No Ordinary Love Lauryn Hill - Ex-Factor ``` ## What it produces The agent outputs a `ShowPrepPackage` component — a single container holding all prep elements for the show: | Component | What it contains | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`TrackContextCard`** | One per track: origin story, production details, genre connections, influence chain, the detail listeners can't Google, why this audience cares now, Milwaukee connection if any, pronunciation guide, and album art | | **`TalkBreakCard`** | One per transition: short (10–15 sec), medium (30–60 sec), and long (60–120 sec) versions, bold key phrases for on-air delivery, cue timing, and pronunciation guide | | **`SocialPostCard`** | One per track or for the show overall: Instagram caption, X/Twitter line with hashtag, and a Bluesky community-oriented version | | **`InterviewPrepCard`** | If a guest is specified: warm-up questions, deep-dive questions, Milwaukee connection question, and a note on which questions to avoid | | **`ConcertEvent`** | Milwaukee-area upcoming shows from Ticketmaster, with venue, date, time, price, and ticket link | ## Structured form syntax For more control, use the structured form with bracket metadata: ``` /prep [station=HYFIN|shift=evening|dj=Tarik|include=context,breaks] Erykah Badu - On & On D'Angelo - Brown Sugar J Dilla - Won't Do ``` ### Metadata fields | Field | Description | | --------- | ------------------------------------------------------------ | | `station` | `HYFIN`, `88Nine`, or `Rhythm Lab` | | `shift` | Time of day — `morning`, `afternoon`, `evening`, `overnight` | | `dj` | DJ name, used in talk break copy | | `guest` | Guest name, triggers `InterviewPrepCard` generation | | `include` | Comma-separated list of sections to generate (see below) | ### `include=` options Omitting `include` generates the full prep package. To request only specific sections: | Value | What it generates | | ----------- | ------------------------------------------- | | `context` | `TrackContextCard` for each track | | `breaks` | `TalkBreakCard` for each transition | | `social` | `SocialPostCard` for each track | | `events` | `ConcertEvent` entries from Ticketmaster | | `interview` | `InterviewPrepCard` for the specified guest | Use `include=context,breaks` for a focused prep session when you already have your social copy handled. ## Research strategy The agent budgets tool calls based on setlist length: * Up to 8 tracks are fully researched using `research_track` (Perplexity-powered) — one call per track returns origin story, production details, connections, and on-air hook * Tracks beyond 8 are covered from the agent's general knowledge * If the setlist has 4 or fewer tracks, the agent also fetches album art from iTunes * After research, one Ticketmaster call fetches Milwaukee concert events (if `events` is included) The agent outputs only the `ShowPrepPackage` OpenUI block — no narration before or after. All research context is embedded in the component fields. ## Related commands Deep dive on a single track before adding it to prep Daily music news segments to pair with your show Full artist profile for a guest or featured artist Narrative deep dive on an album in your setlist # /story — Story card Source: https://tmoody1973-crate-web-34.mintlify.app/commands/story Rich narrative deep dives on albums, artists, genres, labels, and movements The `/story` command generates a rich narrative `StoryCard` component about any music subject — an album, artist, genre, label, event, or movement. The result includes multiple narrative chapters, a YouTube embed, a mini-playlist of key tracks, key people cards, and cited sources. ## Syntax ``` /story [topic] ``` | Parameter | Description | | --------- | --------------------------------------------------- | | `topic` | Any album, artist, genre, label, event, or movement | ## Examples ``` /story Donuts ``` ``` /story Detroit techno ``` ``` /story Blue Note Records ``` ## What it produces The agent outputs a `StoryCard` component with: | Section | Content | | ----------------- | ---------------------------------------------------------------------------------------------------------- | | **Hero** | Cover art or iconic image, title, subtitle (artist · year · label or relevant context), and category label | | **Key facts** | 3–5 stats — track count, samples used, sales figures, chart positions, or other relevant data | | **Chapters** | 3–5 narrative chapters, each with a title, subtitle, and 2–4 paragraphs of content | | **YouTube embed** | Documentary, interview, or historical footage sourced from a real search result | | **Key tracks** | Tracks mentioned in the story, rendered as a playable mini-playlist | | **Key people** | Important people mentioned in the narrative with their roles | | **Sources** | Cited source links from the research | ## Topics the command works for `/story Donuts`, `/story Kind of Blue`, `/story Illmatic` `/story Alice Coltrane`, `/story Sun Ra` `/story Detroit techno`, `/story Afrobeat`, `/story Chicago house` `/story Blue Note Records`, `/story Stones Throw Records` `/story Golden Age hip-hop`, `/story the jazz loft era` `/story Woodstock 1969`, `/story Detroit electronic music festival` ## Research steps One call to get a comprehensive narrative overview — this works for albums, artists, genres, movements, labels, and events in a single request. For albums: `search_itunes_albums` for the cover art. For genres or movements: an iconic album cover from the era. If no image is found, the component uses a gradient fallback. The agent never fabricates image URLs. Searches for `[topic] documentary` or `[topic] history` and uses a video ID from actual search results. The agent never guesses a YouTube video ID. The agent's entire response will be the `StoryCard` component — no introductory text, no narration. This is by design. If you want to explore a specific element further, use `/track`, `/artist`, or `/influence` after reading the story. ## Related commands Full tabbed artist profile with discography Trace an artist or genre's musical connections Deep dive on a specific track mentioned in the story Turn the story's key tracks into radio show prep # /track — Track deep dive Source: https://tmoody1973-crate-web-34.mintlify.app/commands/track Full track research with credits, samples, lyrics, and vinyl pressings The `/track` command researches a song across Discogs, WhoSampled, MusicBrainz, Genius, and iTunes, then renders a `TrackCard` component with tabbed views covering every dimension of the track. ## Syntax ``` /track [song] [artist] ``` | Parameter | Description | | --------- | --------------------------------------------- | | `song` | Track title | | `artist` | Artist name — include this for disambiguation | ## Example ``` /track So What Miles Davis ``` ## What it produces The agent outputs a `TrackCard` component with the following tabs: | Tab | Content | | ------------------- | ----------------------------------------------------------------------------------------------------------- | | **Credits** | Musicians, writers, producers, engineers, and label details sourced from MusicBrainz and Discogs | | **Sample tree** | Two-direction view: what the track samples, and which tracks have sampled it | | **Lyrics** | Notable Genius annotations and contextual trivia (no full lyrics — just the details listeners can't Google) | | **Vinyl pressings** | Original pressing details, total pressing count, median price, and cover art from Discogs | ## Research steps First call — gets the full recording story: studio context, who played on it, cultural impact, and interesting facts. This becomes the narrative context shown in the component header. Production credits, pressing count, median market price, original label and catalog number, and cover art URL. Samples this track uses (direction: `from`) with element type — drum break, bassline, melody, etc. — and tracks that have sampled this song (direction: `by`). Additional musician and writer credits if not fully covered by Perplexity or Discogs. A notable annotation or production trivia. The agent does not include full song lyrics — only contextual details. Album art fallback if Discogs did not return cover art. ## Sample tree fields Each sample entry in the tree includes: | Field | Description | | ----------- | -------------------------------------------------------------------------------- | | `name` | Sample track title | | `artist` | Sample track artist | | `year` | Year of the sampled recording | | `direction` | `from` = track this song samples; `by` = track that samples this song | | `element` | Sampled element (drum break, bassline, hook, etc.) — included for `from` entries | ## Related commands Full artist profile for the track's creator Narrative deep dive on the album this track appears on Influence map for the artist behind the track Generate talk breaks and context cards for this track The agent intentionally skips full lyrics and only pulls Genius annotations. This keeps the focus on production context and avoids copyright issues. # Google Docs Source: https://tmoody1973-crate-web-34.mintlify.app/integrations/google-docs Save research as shareable Google Docs with one click Connect Google to save research as a formatted document in your Google Drive. The agent creates the doc, inserts the content, and returns a shareable link — no copying and pasting required. Digcrate uses Auth0 Token Vault for the Google connection. Your Google credentials and raw access tokens are never stored by Digcrate — Auth0 handles the token exchange at runtime. ## What you can do Any research output can be saved as a new document in your Google Drive with a title you provide. The agent returns a direct `docs.google.com` link as soon as the document is created. ## How to connect Click the gear icon in the sidebar, or press `Shift+S`. Select the **Connected Services** tab. An OAuth popup opens and redirects you to Google's authorization page. Review the permissions and click **Allow**. You are returned to Digcrate automatically. ## Permissions requested | Scope | What it allows | | ------------ | ---------------------------------------------- | | `documents` | Create and edit Google Docs | | `drive.file` | Access files created by Digcrate in your Drive | The `drive.file` scope gives Digcrate access only to documents it creates — not your entire Drive. ## How to save research to Google Docs You can save a doc in two ways: **Ask the agent directly** — After any research response, say "save this to Google Docs" or "save this as a doc called \[title]". The agent creates the document and returns the link. **Use the action button** — Some research components include a **Save to Google Docs** button. Clicking it triggers the same flow and returns a link when done. Give the document a descriptive title in your request — for example, "save this as 'Flying Lotus Influence Chain'". The title becomes the document's name in your Drive and is easier to find later. ## What gets saved The agent passes the research content as plain text to the Google Docs API, which inserts it at the start of the document. The document is created in your Drive root folder. You can move it, share it, or edit it like any other Google Doc after it is created. The agent returns: * A direct link to the document (`docs.google.com/document/d/...`) * The document title * Confirmation that the save succeeded # Connected services Source: https://tmoody1973-crate-web-34.mintlify.app/integrations/overview Connect Spotify, Slack, and Google Docs to act on your research Digcrate integrates with Spotify, Slack, and Google Docs so you can do more than just read your research — you can save it, share it, and act on it. Each integration uses a standard OAuth flow; you grant permissions on the service's own login page and Digcrate never sees or stores your raw credentials. Digcrate uses Auth0 Token Vault to handle all OAuth token exchange. Your raw access tokens are stored and managed by Auth0 — not Digcrate. When the agent needs to call an external service on your behalf, it retrieves a short-lived token from Auth0 at runtime. ## What you can do Browse your library, view playlists and top artists, and export research as new playlists directly to your account Send research to any channel or DM with rich Block Kit formatting — headers, bullet lists, tables, and dividers Save research as a formatted Google Doc in your Drive and share it with a link ## How connecting works Every integration follows the same OAuth flow. You are always redirected to the service's own login and permissions page — Digcrate is never involved in handling your password or raw token. Click the gear icon in the sidebar, or press `Shift+S`, to open **Settings**. Select the **Connected Services** tab. Click **Connect** next to Spotify, Slack, or Google. An OAuth popup opens. Log in and grant permissions on the service's own authorization page. You are then returned to Digcrate automatically. Connected services are available on all plans — Free, Pro, and Team. You do not need a paid plan to connect Spotify, Slack, or Google. ## Revoking a connection To disconnect a service, go to **Settings → Connected Services** and click **Disconnect** next to the service. You can also revoke Digcrate's access directly from within each service (for example, Spotify's Connected Apps page or Google's account permissions page). # Slack Source: https://tmoody1973-crate-web-34.mintlify.app/integrations/slack Send research to any channel or DM with rich Block Kit formatting Connect Slack to send research directly to your workspace — to a channel or as a DM. Messages are formatted using Slack's Block Kit, so your research arrives with structure: headers, bullet lists, tables, dividers, and a Digcrate footer link. Digcrate uses Auth0 Token Vault for the Slack connection. Your Slack credentials are never stored by Digcrate — Auth0 handles token exchange at runtime. ## What you can do Send research to any public or private channel the Slack app has access to. Send research directly to a teammate using `@username`. Research is automatically converted to Slack Block Kit — headers, bullets, numbered lists, tables, blockquotes, and dividers. The agent renders a clickable channel grid so you never have to type a channel name manually. ## How to connect Click the gear icon in the sidebar, or press `Shift+S`. Select the **Connected Services** tab. An OAuth popup opens and redirects you to Slack's authorization page. Select the workspace you want to connect and click **Allow**. You are returned to Digcrate automatically. ## Permissions requested | Scope | What it allows | | --------------- | --------------------------------- | | `chat:write` | Post messages to channels and DMs | | `channels:read` | List public and private channels | ## How to send research to Slack You can trigger a Slack send in two ways: **Ask the agent directly** — Say something like "send this to #music-production" or "send to @jane". The agent calls `list_slack_channels` first, renders the **SlackChannelPicker** component so you can confirm or change the destination, then posts the message. **Use the action button** — Any research component with a **Send to Slack** button will prompt the channel picker and send the current component's content. You never need to type a channel name or ID. The agent always fetches your channel list first and shows a clickable picker — just click the channel you want. ## How messages are formatted The agent converts research content to Slack Block Kit before sending. The formatting rules are: | Markdown input | Slack Block Kit output | | ------------------ | ----------------------------------- | | `## Heading` | Bold `rich_text` section header | | `- bullet item` | `rich_text_list` with bullet style | | `1. numbered item` | `rich_text_list` with ordered style | | `> blockquote` | `rich_text_quote` block | | `\| table \|` | Native Slack table block | | `---` | Divider block | | `**bold**` | Slack `*bold*` formatting | Every message includes a **Digcrate** footer link at the bottom. ## Troubleshooting **Channel not found** — The Slack app may not have been invited to the channel. Run `/invite @YourApp` in the channel and try again. **Not in channel** — Same as above. Invite the app to the private channel first. **Token expired** — If you see an `invalid_auth` error, go to **Settings → Connected Services** and reconnect Slack. **Missing scope** — If a permission was not granted during setup, disconnect and reconnect Slack to re-authorize with the full scope set. # Spotify Source: https://tmoody1973-crate-web-34.mintlify.app/integrations/spotify Browse your library, create playlists, and export influence chains directly to Spotify Connect Spotify to let the Digcrate agent read your library and create playlists on your behalf. Once connected, the agent can pull in your personal listening data to give context to research and save tracklists straight to your account. Digcrate uses Auth0 Token Vault for the Spotify connection. Your Spotify credentials and raw access tokens are never stored by Digcrate — Auth0 handles the token exchange at runtime. ## What you can do Read your saved tracks, playlists, and top artists. The agent can reference your library when making recommendations or building context. List all your playlists and read the tracks inside them by name — no playlist IDs required. Fetch your medium-term top artists (up to 50) including genres and artwork. Export any TrackList component or influence chain as a new public playlist in your Spotify account. ## How to connect Click the gear icon in the sidebar, or press `Shift+S`. Select the **Connected Services** tab. An OAuth popup opens and redirects you to Spotify's authorization page. Spotify will show the permissions Digcrate is requesting. Click **Agree** to connect. You are returned to Digcrate automatically. ## Permissions requested When you authorize Digcrate, Spotify grants the following scopes: | Scope | What it allows | | ------------------------- | ------------------------------------------ | | `user-library-read` | Read your saved tracks | | `user-top-read` | Read your top artists | | `playlist-read-private` | Read your private and public playlists | | `playlist-modify-public` | Create and add tracks to public playlists | | `playlist-modify-private` | Create and add tracks to private playlists | ## What the agent can do Once connected, the agent has access to three tools: **Read your library** — The agent can fetch your saved tracks, top artists, or playlist list. For example, ask "what are my top artists?" or "show me my saved tracks." **Read playlist tracks** — If you ask the agent to look at a specific playlist, it fetches the full track list automatically. You never need to provide a playlist ID. **Export to Spotify** — The agent searches Spotify for each track by artist and title, creates a new playlist in your account, and adds the matched tracks. Tracks that cannot be found on Spotify are reported back. ## Creating a playlist from research During any research session, if the agent returns a TrackList — for example, an influence chain or a set of recommendations — you can ask it to save that list as a Spotify playlist. Try saying "save this as a Spotify playlist called \[name]" after any TrackList appears, or click the **Export to Spotify** action button on the component. The agent will create the playlist and return a direct link. Playlists are created as public by default. The agent reports how many tracks were added and which ones, if any, it could not find on Spotify. # Introduction Source: https://tmoody1973-crate-web-34.mintlify.app/introduction AI-powered music research for DJs, producers, and crate diggers. 20+ sources. One agent. Zero tabs. Digcrate is a conversational music research workspace where an AI agent searches across Discogs, MusicBrainz, Last.fm, Genius, WhoSampled, Bandcamp, Wikipedia, Ticketmaster, Spotify, and more — returning interactive visual components instead of walls of text. Ask about any artist, track, sample, or genre. Connect your Spotify, Slack, and Google accounts to act on what you find. Create your account and run your first research query in minutes Learn how the chat panel, Deep Cuts, and audio player work together Slash commands for artist profiles, track deep dives, influence maps, and more Connect Spotify, Slack, and Google Docs to act on your research Free, Pro, and Team plans — or bring your own API key Build reusable slash commands tailored to your workflow ## What Digcrate does Digcrate runs a multi-step AI agent that calls across 20+ specialized music databases in parallel, then renders the results as interactive components — artist profiles with playable discographies, influence chains you can tap through, track deep dives with credits and sample trees, and more. Full artist profiles with discography, influences, similar artists, and media Credits, samples, lyrics, annotations, and vinyl pressing details in one view Trace an artist's connections through reviews, collaborations, and co-mentions Track context, talk breaks, and social copy for radio DJs Narrative deep dives on albums, genres, labels, and movements Stream any of 30,000+ radio stations directly in the workspace ## Data sources Digcrate queries across 20+ specialized sources so you don't have to: | Source | What it provides | | ------------------------- | ----------------------------------------------------- | | Discogs | Releases, labels, credits, cover art, vinyl pressings | | MusicBrainz | Artist metadata, relationships, recordings | | Last.fm | Similar artists, tags, listening stats | | Genius | Lyrics, annotations, song metadata | | WhoSampled | Sample origins, covers, remixes | | Bandcamp | Album search, tag exploration | | Wikipedia | Artist bios, discography context | | Ticketmaster | Concert listings, ticket availability | | Spotify | Library, playlists, top artists (via connection) | | YouTube | Music videos, documentaries | | Perplexity / Exa / Tavily | Web research with citations | | Radio Browser | 30,000+ live radio stations | ## Self-hosting Digcrate is open source. If you want to run your own instance, see the [self-hosting guides](/self-hosting/prerequisites). # Quick Start Source: https://tmoody1973-crate-web-34.mintlify.app/quickstart Get from sign-up to your first research query in under 5 minutes Go to [digcrate.app](https://digcrate.app) and create an account. Sign-in is handled by Clerk — you can use email or an OAuth provider. On your first sign-in, a quick start wizard walks you through adding an API key. You can skip this and use the 10 free queries included on the Free plan. Click **New Chat** in the sidebar, or press `Cmd+N`. Each session is an independent research conversation. Your sessions are saved automatically and appear in the sidebar under **Recents**. On mobile, tap the hamburger menu to open the sidebar and start a new session. Type your question in the chat input and press **Enter**. The simplest way to start is with the `/artist` command: ``` /artist MF DOOM ``` The agent searches across MusicBrainz, Discogs, Last.fm, Genius, YouTube, and more, then renders an interactive **ArtistProfile** component directly in the chat. Click it to open the full profile in the **Deep Cuts** panel on the right. You can also ask in plain language — the agent handles both: ``` Who influenced Flying Lotus? What's the story behind Donuts? Map the LA beat scene ``` When the agent returns a rich component (an artist profile, influence map, playlist, or show prep package), it automatically appears in the **Deep Cuts** panel. The panel saves everything from your current session so you can switch between results using the dropdown selector at the top. To share a result, click **Publish** in the Deep Cuts header. This generates a shareable link at `digcrate.app/cuts/[id]` and copies it to your clipboard. Publishing requires a Pro or Team plan. On the Free plan, results are visible only within your session. ## Slash commands Type `/` in the chat input to see the full command menu. Use arrow keys to navigate and `Tab` or `Enter` to select. | Command | What it does | | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | | `/artist [name]` | Full artist deep dive — tabbed discography, influence connections, media, top tracks | | `/track [song] [artist]` | Track deep dive — credits, samples (WhoSampled), lyrics (Genius), vinyl pressings (Discogs) | | `/influence [artist]` | Interactive influence map tracing connections through reviews, Last.fm similarity, and Perplexity research | | `/story [topic]` | Narrative deep dive with chapters, YouTube embeds, key tracks, and people cards | | `/prep [station]: [setlist]` | Full radio show prep — track context, talk breaks, social copy, interview prep | | `/news [station] [count]` | Daily music news segment from RSS feeds and web search | | `/radio [genre or station]` | Search and stream any of 30,000+ live radio stations | | `/create-skill [description]` | Teach Digcrate a new reusable command | | `/skills` | List, enable, disable, and edit your custom skills | | `/publish telegraph` | Publish research to a shareable Telegraph article (Pro) | ## Add your own API key (BYOK) The Free plan includes 10 agent queries per month. To get unlimited queries, bring your own key from Anthropic or OpenRouter. 1. Open **Settings** (`Shift+S` or the gear icon in the sidebar). 2. Go to the **API Keys** tab. 3. Paste your Anthropic key (`sk-ant-...`) or OpenRouter key. 4. Click **Save** — your key is encrypted and stored securely. With a BYOK key, queries run against your key with no monthly cap. OpenRouter gives you access to multiple models (GPT-4o, Gemini 2.5, Llama 4, DeepSeek R1, Mistral Large) in addition to Claude. Use the model selector in the chat header to switch. # Architecture Source: https://tmoody1973-crate-web-34.mintlify.app/self-hosting/architecture How Digcrate's components fit together ## Overview Digcrate is a Next.js application with a Convex real-time backend. The browser communicates with serverless API routes on Vercel, which in turn talk to Convex (database), Anthropic (AI), and MCP tool servers (music data). ``` Browser (Next.js App Router) │ ├── Clerk (auth middleware) │ ├── POST /api/chat ─────────────────────── Vercel serverless │ │ │ │ │ agentic-loop.ts │ │ │ │ │ │ Anthropic SDK OpenRouter │ │ │ │ │ tool_use calls │ │ │ │ │ crate-cli MCP servers │ │ (Discogs, MusicBrainz, Last.fm, …) │ │ │ └── SSE stream ──────────────────── Browser │ (thinking, tool_start, tool_end, answer_token, done) │ └── Convex subscriptions (real-time) (sessions, messages, artifacts, playlists, usage) ``` *** ## Tech stack | Layer | Technology | Purpose | | ------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------- | | Framework | Next.js 16 (App Router) | SSR, API routes, Turbopack dev | | Deployment | Vercel | Serverless functions | | Auth | Clerk | User sign-in, OAuth | | Connected services | Auth0 Token Vault | OAuth connections for Spotify, Slack, Google | | Database | Convex | Real-time sessions, messages, playlists, collections, influence graph, subscriptions, skills, shares | | Dynamic UI | OpenUI (`@openuidev/react-lang`) | Agent-generated interactive components | | Agent | Anthropic SDK + agentic loop | Tool-use loop with crate-cli MCP servers | | Billing | Stripe | Checkout, billing portal, webhooks | | Styling | Tailwind CSS v4 | Dark theme, responsive mobile | | Audio | YouTube IFrame API | Persistent player bar | | Analytics | PostHog | Product analytics, LLM observability | *** ## Project structure ``` crate-web/ ├── convex/ # Convex backend (schema + query/mutation functions) │ ├── schema.ts # Database schema (26 tables) │ ├── sessions.ts # Chat session CRUD │ ├── messages.ts # Message persistence │ ├── playlists.ts # Playlist management │ ├── subscriptions.ts # Stripe subscription state │ ├── usage.ts # Usage tracking and quotas │ ├── userSkills.ts # Custom skill CRUD │ ├── shares.ts # Published Deep Cut shares │ └── users.ts # User sync (Clerk → Convex) ├── src/ │ ├── app/ │ │ └── api/ │ │ ├── chat/route.ts # SSE streaming — agentic loop entry point │ │ ├── auth0/ # OAuth connect, callback, status │ │ ├── stripe/ # Checkout, billing portal, webhooks │ │ ├── skills/ # Custom skill management │ │ └── keys/route.ts # User API key management │ ├── components/ │ │ ├── workspace/ # Chat panel, Deep Cuts panel, workspace shell │ │ ├── sidebar/ # Desktop and mobile sidebar │ │ ├── settings/ # Connected services, plan, skills, keys │ │ └── player/ # YouTube audio player │ └── lib/ │ ├── agentic-loop.ts # Core agent loop (Anthropic + OpenRouter) │ ├── openui/ # 27+ OpenUI component definitions and registry │ ├── web-tools/ # Connected service tools (Spotify, Slack, Google) │ ├── auth0-token-vault.ts # OAuth token exchange via Auth0 Management API │ └── plans.ts # Subscription tiers and rate limiting ``` *** ## The agentic loop Every user message goes through a multi-turn tool-use loop implemented in `src/lib/agentic-loop.ts`. 1. The browser sends a `POST` to `/api/chat` with the message, session history, model choice, and API key. 2. The route handler builds the tool list from `crate-cli` MCP servers and calls `agenticLoop()`. 3. The loop calls the Anthropic (or OpenRouter) API with the message and available tools. 4. If the model returns `tool_use` blocks, the loop executes each tool call against the appropriate MCP server. 5. Tool results are fed back to the model as `tool_result` blocks. Steps 3–5 repeat up to 25 turns. 6. Each turn emits Server-Sent Events to the browser: `thinking`, `tool_start`, `tool_end`, `answer_token`, and finally `done`. 7. The browser's chat panel renders tokens as they arrive and parses OpenUI components from the final answer. The loop supports both Anthropic (direct SDK) and OpenRouter (OpenAI-compatible API) with the same event format. The `useOpenRouter` flag on `AgenticLoopOptions` selects the path. *** ## Key data flows ### Authentication ``` Request arrives → Clerk middleware checks session token → Authenticated: request proceeds with userId → Unauthenticated: redirect to /sign-in ``` User records are synced from Clerk to Convex via a webhook at `/api/webhooks/clerk`. The Convex `users` table stores the Clerk user ID, email, encrypted API keys, and Stripe customer ID. ### Agent query ``` POST /api/chat → Validate Clerk session, load subscription + usage → Check quota (free: 10/month, pro: 50/month, team: 200/month pooled) → Build tool groups from crate-cli MCP servers → agenticLoop() → Anthropic SDK → tool calls → MCP servers → Stream CrateEvents as SSE → On done: write message + artifacts to Convex ``` ### Real-time state (Convex) The browser subscribes to Convex queries that push updates in real time: | Subscription | What updates | | --------------------------- | ----------------------- | | `sessions.listByUser` | Sidebar session list | | `messages.listBySession` | Chat message history | | `artifacts.listBySession` | Deep Cuts panel | | `playlists.listByUser` | Playlist library | | `usage.getForCurrentPeriod` | Usage meter in settings | ### Connected services (Auth0 Token Vault) ``` User clicks "Connect Spotify" in Settings → GET /api/auth0/connect?service=spotify → Generates CSRF nonce, redirects to Auth0 /authorize → User grants permissions on Auth0 / Spotify consent screen → Auth0 redirects to /api/auth0/callback → Callback extracts Auth0 user ID, sets secure cookie Agent calls read_spotify_library tool → getTokenVaultToken("spotify", auth0UserId) → Fetches Management API token (cached 23 hours) → GET /api/v2/users/{userId}?fields=identities → Returns access_token from the Spotify identity → Tool calls Spotify Web API with the token ``` *** ## Database schema The Convex database has 24 tables. Key tables: | Table | Purpose | | ------------------------------------- | --------------------------------------------------------------- | | `users` | User accounts with Clerk ID, encrypted keys, Stripe customer ID | | `crates` | Named session folders for organizing research | | `sessions` | Chat sessions (title, crate membership, starred, archived) | | `messages` | Chat messages (user and assistant roles) | | `artifacts` | Saved research components (Deep Cuts) | | `toolCalls` | Tool execution log per session | | `playerQueue` | Audio player queue tracks per session | | `playlists` / `playlistTracks` | User playlists with track metadata | | `collection` | Vinyl collection records | | `subscriptions` | Stripe subscription state | | `usageEvents` | Per-user, per-period query count | | `userSkills` | Custom slash commands | | `shares` | Published Deep Cut share records | | `influenceArtists` / `influenceEdges` | Cached influence graph nodes and edges | | `telegraphAuth` / `telegraphEntries` | Telegraph publishing credentials and posts | | `tumblrAuth` / `tumblrPosts` | Tumblr publishing credentials and posts | | `orgKeys` | Team-level shared API keys by domain | # Data sources Source: https://tmoody1973-crate-web-34.mintlify.app/self-hosting/data-sources The 20+ music databases and APIs that power Digcrate's research Digcrate's agent queries across 20+ specialized data sources in a single research session. These integrations are provided by the [`crate-cli`](https://github.com/tmoody1973/crate-cli) npm package — Digcrate imports MCP tool servers from `crate-cli` rather than implementing them directly. Each tool server exposes a set of MCP-compatible tools. The agent selects which tools to call based on the query, then executes them in sequence or parallel as needed. *** ## Music databases These are the core sources for music metadata, credits, samples, and discovery. | Source | Data provided | | --------------- | ------------------------------------------------------------------------------------------ | | **Discogs** | Releases, labels, master recordings, credits, cover art, vinyl pressings, marketplace data | | **MusicBrainz** | Artist metadata, relationships, recordings, release groups, work credits | | **Last.fm** | Similar artists, genre tags, listener counts, top tracks, listening stats | | **Genius** | Lyrics, annotations, song metadata, writer and producer credits | | **WhoSampled** | Sample origins, interpolations, covers, and remixes | | **Bandcamp** | Album search, tag exploration, related tags, artist pages | **API keys required**: Discogs (`EMBEDDED_DISCOGS_KEY` + `EMBEDDED_DISCOGS_SECRET`) and Last.fm (`EMBEDDED_LASTFM_KEY`) need keys set in your environment. MusicBrainz, Genius, WhoSampled, and Bandcamp are accessed without authentication. *** ## General knowledge | Source | Data provided | | ------------- | ----------------------------------------------------------------------- | | **Wikipedia** | Artist biographies, discography context, genre history, label histories | No API key required. Wikipedia is accessed via the public MediaWiki REST API. *** ## Events | Source | Data provided | | ---------------- | ----------------------------------------------------------------- | | **Ticketmaster** | Concert listings, ticket availability, venue details, event dates | **API key required**: Set `EMBEDDED_TICKETMASTER_KEY` in your environment. Get a key at [developer.ticketmaster.com](https://developer.ticketmaster.com). *** ## Connected (via Auth0 Token Vault) These sources require the user to connect their account through Settings. The connection is managed by Auth0 Token Vault — Digcrate never stores raw OAuth tokens. | Source | Data provided | | ----------- | -------------------------------------------------------------------------------------------------------------- | | **Spotify** | User library, saved albums, followed artists, playlists, top artists, top tracks. Create and export playlists. | Spotify integration requires Auth0 Token Vault to be configured (`AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`). See [Environment variables](/self-hosting/environment-variables) and [Deployment](/self-hosting/deployment) for setup instructions. *** ## Images and media | Source | Data provided | | ------------- | ---------------------------------------------------------------- | | **fanart.tv** | High-resolution artist backgrounds, logos, album art, thumbnails | | **iTunes** | Album artwork, track search, artist lookup | | **YouTube** | Music videos, documentaries, live performances, interviews | No API keys required for these sources in standard use. *** ## Web research These sources extend the agent beyond structured databases into open-web research with citations. | Source | Data provided | | ---------------------- | -------------------------------------------------------------------------------------------------------- | | **Exa.ai** | Semantic web search — finds conceptually relevant articles, reviews, and blog posts | | **Tavily** | AI-optimized web search with structured result extraction | | **Perplexity (Sonar)** | Research enrichment with inline citations. Used for influence mapping pull quotes and show prep context. | Exa, Tavily, and Perplexity each require their own API keys, which users configure in the **Settings → API Keys** panel within the app. These keys are stored encrypted in Convex and sent to the agent at runtime. They are not set as server-side environment variables. *** ## Memory | Source | Data provided | | -------- | ------------------------------------------------------------------------------------------------------------------- | | **Mem0** | Cross-session user memory. The agent can remember preferences, saved artists, and research context across sessions. | Mem0 is available on the Pro plan. Users configure their Mem0 API key in **Settings → API Keys**. *** ## Radio | Source | Data provided | | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | | **Radio Browser** | 30,000+ live radio stations searchable by genre, country, name, or tag. Streams directly in the workspace audio player. | No API key required. Radio Browser is accessed via the public community API. *** ## How tool selection works When a user sends a query, the agent receives the full list of available tools from all MCP servers. It decides which tools to call based on the query content and the system prompt. The agentic loop executes tool calls sequentially, feeding results back to the model until it has enough information to write a final answer. For research-heavy commands (e.g. `/influence`, `/story`, `/track`), the agent gets a higher tool-call cap to allow deeper multi-source lookups. For conversational queries, it may use only one or two tools or none at all. The tool execution log for each session is visible in the chat panel as collapsible "thinking" steps, showing which sources were queried and how long each call took. # Deployment Source: https://tmoody1973-crate-web-34.mintlify.app/self-hosting/deployment Deploy Digcrate to Vercel with a Convex backend This guide covers deploying Digcrate to production on Vercel with a Convex backend. Complete the [prerequisites](/self-hosting/prerequisites) and prepare your [environment variables](/self-hosting/environment-variables) before starting. ```bash theme={null} git clone https://github.com/tmoody1973/crate-web.git cd crate-web npm install ``` Copy the example env file and fill in your values: ```bash theme={null} cp .env.local.example .env.local ``` See [Environment variables](/self-hosting/environment-variables) for a full reference of every variable. Convex requires two steps — one for local development and one for production. **Local development** Run the Convex dev server to create a development deployment and push your schema: ```bash theme={null} npx convex dev ``` This writes `NEXT_PUBLIC_CONVEX_URL` and `CONVEX_DEPLOYMENT` to your `.env.local` automatically. **Production deployment** When you are ready to go to production, deploy Convex to a production environment: ```bash theme={null} npx convex deploy --yes ``` Copy the production `NEXT_PUBLIC_CONVEX_URL` output — you will need it in the next step. During local development you need both servers running at the same time. Open two terminal tabs: * **Terminal 1**: `npx convex dev` * **Terminal 2**: `npm run dev` The Convex dev server syncs your schema and functions to the cloud in real time. Next.js reads the `NEXT_PUBLIC_CONVEX_URL` from `.env.local` to connect. Install the Vercel CLI and deploy: ```bash theme={null} npm i -g vercel vercel --prod ``` Follow the prompts to link the project to your Vercel account. Vercel will detect Next.js automatically and configure the build settings. After deploying, add all environment variables in the Vercel dashboard: 1. Open your project in the [Vercel dashboard](https://vercel.com/dashboard). 2. Go to **Settings → Environment Variables**. 3. Add each variable from your `.env.local`, using the production values (production Convex URL, live Stripe keys, production Auth0 callback URL, etc.). Key differences between local and production values: | Variable | Local value | Production value | | ------------------------------------ | ------------------------------------------ | ------------------------------------------- | | `NEXT_PUBLIC_CONVEX_URL` | Dev deployment URL | Production deployment URL | | `STRIPE_SECRET_KEY` | `sk_test_...` | `sk_live_...` | | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | `pk_test_...` | `pk_live_...` | | `AUTH0_CALLBACK_URL` | `http://localhost:3000/api/auth0/callback` | `https://yourdomain.com/api/auth0/callback` | After saving, redeploy for the new variables to take effect: ```bash theme={null} vercel --prod ``` Digcrate uses a Stripe webhook to process subscription events (checkout completed, subscription updated, invoice paid, etc.). 1. In the [Stripe dashboard](https://dashboard.stripe.com), go to **Developers → Webhooks**. 2. Click **Add endpoint**. 3. Set the endpoint URL to `https://yourdomain.com/api/webhooks/stripe`. 4. Select the following events to listen for: * `checkout.session.completed` * `customer.subscription.updated` * `customer.subscription.deleted` * `invoice.payment_succeeded` * `invoice.payment_failed` 5. Copy the **Signing secret** and set it as `STRIPE_WEBHOOK_SECRET` in Vercel. If you are not enabling subscription billing, you can skip this step. All users will be on the free tier. If you want to enable Spotify, Slack, and Google Docs integrations, configure Auth0: 1. In the [Auth0 dashboard](https://manage.auth0.com), create a new application of type **Regular Web Application**. 2. Under **Settings**, add your production callback URL to **Allowed Callback URLs**: ``` https://yourdomain.com/api/auth0/callback ``` 3. Enable the **Token Vault** feature under **Connections** and configure the Spotify, Slack, and Google OAuth connections. 4. Copy the **Domain**, **Client ID**, and **Client Secret** from the Auth0 application settings and set them as environment variables in Vercel. Auth0 Token Vault is optional. Skip this step if you do not need Spotify, Slack, or Google Docs integration. Open your Vercel deployment URL and: 1. Sign up for an account — Clerk should handle the flow and redirect you to the workspace. 2. Run a test query (e.g. `/artist Radiohead`) — the agent should stream a response. 3. If you configured Stripe, visit `/pricing` and verify the plans appear. 4. Check the Convex dashboard to confirm data is being written to the database. # Environment variables Source: https://tmoody1973-crate-web-34.mintlify.app/self-hosting/environment-variables All environment variables required to run Digcrate Copy `.env.local.example` to `.env.local` and fill in the values below. ```bash theme={null} cp .env.local.example .env.local ``` *** ## Clerk (authentication) Clerk handles user sign-in, sign-up, and session management. ```env theme={null} NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx CLERK_SECRET_KEY=sk_test_xxx CLERK_WEBHOOK_SECRET=whsec_xxx NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up ``` | Variable | Description | | ----------------------------------- | ----------------------------------------------------------------- | | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Client-side Clerk key. Found in your Clerk application dashboard. | | `CLERK_SECRET_KEY` | Server-side Clerk key. Keep this secret. | | `CLERK_WEBHOOK_SECRET` | Webhook signing secret for syncing user records to Convex. | | `NEXT_PUBLIC_CLERK_SIGN_IN_URL` | Path for the sign-in page. Use `/sign-in`. | | `NEXT_PUBLIC_CLERK_SIGN_UP_URL` | Path for the sign-up page. Use `/sign-up`. | *** ## Convex (database) Convex stores all application state — sessions, messages, playlists, usage events, subscriptions, influence graphs, and more. ```env theme={null} NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud ``` | Variable | Description | | ------------------------ | ------------------------------------------------------------------------------------------ | | `NEXT_PUBLIC_CONVEX_URL` | Your Convex deployment URL. Set automatically by `npx convex dev` and `npx convex deploy`. | `CONVEX_DEPLOYMENT` (e.g. `dev:your-project-name`) is written to `.env.local` automatically by the Convex CLI during `npx convex dev`. You do not need to set it manually. *** ## Encryption Used to encrypt API keys stored in the database. ```env theme={null} ENCRYPTION_KEY= ``` | Variable | Description | | ---------------- | ------------------------------------------------------------------------ | | `ENCRYPTION_KEY` | A 64-character hexadecimal string used to encrypt user API keys at rest. | Generate a secure value with: ```bash theme={null} openssl rand -hex 32 ``` Changing `ENCRYPTION_KEY` after users have saved API keys will make those keys unreadable. Store this value securely and do not rotate it without a migration plan. *** ## Platform AI key The Anthropic API key Digcrate uses to serve free and Pro users who have not configured their own key (BYOK). ```env theme={null} PLATFORM_ANTHROPIC_KEY=sk-ant-xxx ``` | Variable | Description | | ------------------------ | --------------------------------------------------------------------------------------------- | | `PLATFORM_ANTHROPIC_KEY` | Your platform-level Anthropic API key. Costs are billed to this key for all non-BYOK queries. | This variable is required for the platform to serve free-tier users. Without it, only BYOK users can run queries. All other users will receive an error when attempting to start a research session. *** ## Admin ```env theme={null} ADMIN_EMAILS=admin@example.com ``` | Variable | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------- | | `ADMIN_EMAILS` | Comma-separated list of email addresses. Users with these emails bypass all rate limits, usage quotas, and feature gates. | *** ## Embedded API keys These keys are embedded in the server and used by the agent's MCP tools. They are optional — the agent will skip tools that lack a key — but enabling them unlocks more data sources. ```env theme={null} EMBEDDED_LASTFM_KEY= EMBEDDED_DISCOGS_KEY= EMBEDDED_DISCOGS_SECRET= EMBEDDED_TICKETMASTER_KEY= ``` | Variable | Description | | --------------------------- | ------------------------------------------------------------------------------------------ | | `EMBEDDED_LASTFM_KEY` | [Last.fm API key](https://www.last.fm/api) for similar artists, tags, and listening stats. | | `EMBEDDED_DISCOGS_KEY` | [Discogs app key](https://www.discogs.com/settings/developers) for release and label data. | | `EMBEDDED_DISCOGS_SECRET` | Discogs app secret, paired with `EMBEDDED_DISCOGS_KEY`. | | `EMBEDDED_TICKETMASTER_KEY` | [Ticketmaster API key](https://developer.ticketmaster.com) for concert listings. | *** ## Stripe (billing) Required to enable subscription plans (Free, Pro, Team) and the billing portal. ```env theme={null} STRIPE_SECRET_KEY=sk_test_xxx NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx STRIPE_WEBHOOK_SECRET=whsec_xxx STRIPE_PRO_MONTHLY_PRICE_ID=price_xxx STRIPE_PRO_ANNUAL_PRICE_ID=price_xxx STRIPE_TEAM_MONTHLY_PRICE_ID=price_xxx ``` | Variable | Description | | ------------------------------------ | -------------------------------------------------- | | `STRIPE_SECRET_KEY` | Server-side Stripe secret key. | | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Client-side Stripe publishable key. | | `STRIPE_WEBHOOK_SECRET` | Webhook signing secret for `/api/webhooks/stripe`. | | `STRIPE_PRO_MONTHLY_PRICE_ID` | Stripe Price ID for the Pro monthly plan. | | `STRIPE_PRO_ANNUAL_PRICE_ID` | Stripe Price ID for the Pro annual plan. | | `STRIPE_TEAM_MONTHLY_PRICE_ID` | Stripe Price ID for the Team monthly plan. | Stripe is optional. If omitted, all users will be treated as free-tier. Subscription upgrades and the billing portal will not be available. *** ## Auth0 Token Vault (connected services) Required to enable Spotify, Slack, and Google Docs integrations. Auth0 Token Vault securely manages OAuth tokens on behalf of users — Digcrate never stores raw credentials. ```env theme={null} AUTH0_DOMAIN=your-tenant.us.auth0.com AUTH0_CLIENT_ID=your-auth0-client-id AUTH0_CLIENT_SECRET=your-auth0-client-secret AUTH0_TOKEN_VAULT_AUDIENCE=https://your-api-audience AUTH0_CALLBACK_URL=http://localhost:3000/api/auth0/callback ``` | Variable | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `AUTH0_DOMAIN` | Your Auth0 tenant domain (e.g. `your-tenant.us.auth0.com`). | | `AUTH0_CLIENT_ID` | Auth0 application client ID. | | `AUTH0_CLIENT_SECRET` | Auth0 application client secret. | | `AUTH0_TOKEN_VAULT_AUDIENCE` | The API audience configured in Auth0 for Token Vault. | | `AUTH0_CALLBACK_URL` | OAuth callback URL. Set to your production domain in production (e.g. `https://yourdomain.com/api/auth0/callback`). | Auth0 Token Vault is optional. Without it, connected services (Spotify, Slack, Google Docs) will not be available to users. *** ## Beta domains ```env theme={null} BETA_DOMAINS=radiomilwaukee.org ``` | Variable | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BETA_DOMAINS` | Comma-separated list of email domains. Users signing up with these email domains automatically receive Pro access at no charge. Useful for beta testers, partner organizations, or radio stations. | This variable is optional. *** ## Optional: Canny feedback widget ```env theme={null} NEXT_PUBLIC_CANNY_APP_ID=your-canny-app-id NEXT_PUBLIC_CANNY_URL=https://your-company.canny.io ``` | Variable | Description | | -------------------------- | ---------------------------------------------------------------- | | `NEXT_PUBLIC_CANNY_APP_ID` | [Canny](https://canny.io) app ID for the in-app feedback widget. | | `NEXT_PUBLIC_CANNY_URL` | Your Canny board URL. | Canny is optional. If omitted, the feedback widget will not appear. # Prerequisites Source: https://tmoody1973-crate-web-34.mintlify.app/self-hosting/prerequisites What you need before setting up a self-hosted Digcrate instance Before you deploy Digcrate, you need accounts with three external services and a few tools installed locally. All required services have free tiers that are sufficient for a personal or small-team instance. Digcrate requires Node.js 20 or later. Check your current version: ```bash theme={null} node --version npm --version ``` If you need to upgrade, download the LTS release from [nodejs.org](https://nodejs.org) or use a version manager like `nvm`: ```bash theme={null} nvm install 20 nvm use 20 ``` You need Git to clone the repository. ```bash theme={null} git --version ``` If Git is not installed, follow the [official installation guide](https://git-scm.com/downloads). Clerk handles user authentication (sign-in, sign-up, sessions). 1. Sign up at [clerk.com](https://clerk.com) — the free tier is sufficient. 2. Create a new application. 3. From the application dashboard, copy your **Publishable Key** (`pk_test_...`) and **Secret Key** (`sk_test_...`). You will need both when configuring environment variables. 4. Note the **Webhook Secret** from the Webhooks section — Digcrate uses this to sync users to Convex. Clerk's free tier includes up to 10,000 monthly active users and all OAuth providers. Convex is the real-time database that stores sessions, messages, playlists, usage events, subscriptions, and all other application state. 1. Sign up at [convex.dev](https://convex.dev) — the free tier is sufficient for most self-hosted instances. 2. You do not need to create a project manually. Running `npx convex dev` during setup will create and configure one automatically. Convex's free tier includes 1M function calls and 1 GB database storage per month. Vercel is the recommended deployment target. Digcrate uses Next.js App Router and serverless API routes, which deploy without any additional configuration on Vercel. 1. Sign up at [vercel.com](https://vercel.com). 2. You can also deploy to any Node.js host that supports Next.js, but Vercel is the path with the least configuration. Vercel's free Hobby tier works for personal instances. Team instances with higher traffic should use a Pro plan. Digcrate's agent runs on Claude. You need an Anthropic API key to power queries for free and Pro users (BYOK users supply their own keys at runtime). 1. Sign up at [console.anthropic.com](https://console.anthropic.com). 2. Create an API key. This becomes the `PLATFORM_ANTHROPIC_KEY` environment variable. Without `PLATFORM_ANTHROPIC_KEY`, only users who have entered their own API key (BYOK) will be able to run queries. Free-tier and Pro users will see an error. The following services are optional depending on which features you want to enable: * **Stripe** — Required for subscription billing (free/pro/team plans and checkout). Sign up at [stripe.com](https://stripe.com). * **Auth0** — Required for connected services (Spotify, Slack, Google Docs via Token Vault). Sign up at [auth0.com](https://auth0.com). * **Last.fm API key** — For similar artists and listening stats. Get a key at [last.fm/api](https://www.last.fm/api). * **Discogs API key** — For release data and cover art. Get a key at [discogs.com/settings/developers](https://www.discogs.com/settings/developers). * **Ticketmaster API key** — For concert listings. Get a key at [developer.ticketmaster.com](https://developer.ticketmaster.com). See [Environment variables](/self-hosting/environment-variables) for the full list. Once you have these accounts and tools ready, continue to [Environment variables](/self-hosting/environment-variables). # Creating a skill Source: https://tmoody1973-crate-web-34.mintlify.app/skills/creating-skills Use /create-skill to teach Digcrate a new reusable command The `/create-skill` command turns a plain-language description into a saved slash command. Digcrate does a real dry run first — using live tools, returning real results — so you can see exactly what the command will do before saving it. ## Workflow Type `/create-skill` followed by a description of what you want the command to do. ``` /create-skill Pull upcoming events from The Rave Milwaukee website ``` Be specific. The more detail you give, the better the dry run results — and the more accurate the saved command will be. Digcrate executes the task right now using its available tools. No questions, no clarifications — it uses your description and its best judgment. For a website task, it navigates to the page and scrapes results. For a search task, it queries the relevant data sources. For research, it runs the same multi-step agent loop as any other query. Results are displayed using OpenUI components — the same components used everywhere in Digcrate: * Event listings → `ConcertList` with venue, date, and ticket links * Records and releases → `TrackList` with links to source pages * Artist research → `ArtistCard` * Playlists → `SpotifyPlaylist` If the data doesn't fit a structured component, results are formatted as a markdown list with clickable links. After the dry run, Digcrate suggests a command name based on your description — for example, `/rave-events`. Command names are lowercase with hyphens. You can accept the suggestion or ask for a different name before saving. Confirm that you want to save the skill. Digcrate calls `save_user_skill` and stores the command to your account immediately. The skill is available right away — type `/rave-events` in any session to run it. ## Worked example Here's what the full flow looks like for a real skill: **Input:** ``` /create-skill Pull upcoming events from The Rave Milwaukee website ``` **Dry run:** Digcrate navigates to therave.com, scrapes the upcoming shows listing, and renders a `ConcertList` with artist names, dates, venues, and ticket links. **Suggested command name:** `/rave-events` **After confirming:** The skill is saved. From now on, typing `/rave-events` in any session runs the same scrape and returns fresh results every time. ## What gets saved When you confirm a skill, Digcrate stores: | Field | What it contains | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Command name** | The slash command, e.g. `rave-events` | | **Name** | Human-readable label, e.g. "The Rave Events" | | **Description** | One sentence describing what the skill does | | **Prompt template** | The full prompt that produced the dry run results, including instructions for OpenUI rendering and clickable links | | **Tool hints** | The names of the tools that worked during the dry run | | **Source URL** | The URL of any website that was involved | The prompt template is what runs each time you invoke the skill. It includes instructions to present results using OpenUI components and to include full URLs on every item so you can click through to the source. ## Editing and deleting skills Use `/skills` to manage your saved commands: * To edit a skill's name or description, select it from the list * To delete a skill, select it and choose **Delete** * To temporarily stop a skill from appearing in autocomplete, disable it without deleting Skills run the same agent loop as every other Digcrate command. They have access to all 20+ data sources — Discogs, MusicBrainz, Last.fm, Ticketmaster, Bandcamp, WhoSampled, Wikipedia, Genius, and more. If you can describe it, you can skill it. # Custom skills Source: https://tmoody1973-crate-web-34.mintlify.app/skills/overview Build reusable slash commands tailored to your workflow Custom skills are slash commands you define. You describe what you want in plain language, Digcrate runs a live dry run using its full set of tools, then saves the result as a command you can reuse any time. Skills are stored to your account and available in every session. They show up in autocomplete alongside built-in commands. ## What skills look like in practice Pull upcoming events from The Rave Milwaukee website — venue, dates, ticket links Check Discogs for new vinyl releases in jazz — sorted by date added, with prices and seller links Find this week's local Milwaukee music news from milwaukeerecord.com and urban Milwaukee sources Skills can target any website, search any data source Digcrate has access to, or combine multiple sources in a single run. ## Skill limits by plan | Plan | Custom skills | Scheduled skills | | ---- | ------------- | ---------------- | | Free | 3 | — | | Pro | 20 | 3 | | Team | 50 | 10 | To create more skills, upgrade your plan in **Settings → Plan**. ## Managing your skills Run `/skills` at any time to see a list of all your custom skills. From the list you can: * **Enable or disable** a skill without deleting it * **Edit** the description or prompt template * **Delete** a skill to free up a slot Disabled skills are hidden from autocomplete but their slots still count against your plan limit. ## Creating a skill See [Creating a skill](/skills/creating-skills) for a full walkthrough of the `/create-skill` workflow. Skills run the same agent loop as every other Digcrate command — they have access to all 20+ data sources, connected services, and OpenUI components. There's nothing you can do manually that a skill can't do automatically. # Workspace overview Source: https://tmoody1973-crate-web-34.mintlify.app/workspace-overview How the chat panel, Deep Cuts, and audio player work together The Digcrate workspace is a split-pane layout. The **chat panel** occupies the left side where you send queries and read responses. The **Deep Cuts panel** opens on the right and displays interactive research components. A persistent **audio player** bar sits at the bottom of the screen. Send queries, run slash commands, and watch the agent work in real time. Save, browse, and publish interactive research components — artist profiles, influence maps, playlists, and more. Persistent YouTube and live radio playback that keeps running as you research. ## Chat panel The chat panel is where all research starts. Type a question or slash command and press **Enter** to submit. ### Starting a query The input placeholder reads "Who influenced Flying Lotus? Try / for commands" when idle and "Crate is researching..." while the agent is running. You can also click one of the suggestion chips on an empty session to prefill a starter query. ### Slash command syntax Type `/` to open the command autocomplete menu. The menu filters as you type and shows each command's usage syntax. Press arrow keys to navigate, then `Tab` or `Enter` to select. Most commands take a single argument directly after the command name: ``` /artist Erykah Badu /influence J Dilla /track So What Miles Davis /story Kind of Blue ``` The `/prep` and `/show-prep` commands open a structured form where you pick a station, shift, and setlist instead of typing everything inline. ### Streaming tool progress While the agent is running, the chat panel shows a live activity feed labeled **Crate**. Each tool call appears as it starts (with an animated pulse dot) and gets a checkmark when it completes. The feed clears when the response finishes streaming. When the agent generates a rich component (an ArtistProfile, InfluenceChain, ShowPrepPackage, etc.), a compact preview card appears inline in the chat. Click the card to open the full component in Deep Cuts. Plain-language questions and short conversational messages go to a lightweight chat tier and do not consume an agent query from your monthly quota. ## Deep Cuts panel Deep Cuts is a resizable panel on the right side of the workspace (desktop) or a full-screen view (mobile). It renders interactive research components using [OpenUI](https://github.com/thesysdev/openui) — the same rendering engine the agent uses to generate them. ### Saving research The agent automatically pushes each generated component to Deep Cuts. You do not need to manually save — every result from the current session is available in the panel history. ### Dropdown selector with type-colored dots The header of the Deep Cuts panel contains a dropdown that lists every result from the current session. Each item shows a colored dot indicating its type: | Color | Type | | ------ | -------------- | | Violet | Influence map | | Cyan | Artist profile | | Green | Playlist | | Amber | Show prep | | Gray | Other research | Click any item in the dropdown to switch to it. The current item label and dot color are always visible in the collapsed header. ### Action buttons Each result type shows relevant action buttons next to the dropdown: * **Spotify** — Open a playlist or artist in Spotify (requires Spotify connected in Settings) * **Export** — Export an influence chain to a new Spotify playlist * **Slack** — Send the result to a Slack channel (requires Slack connected in Settings) * **Publish** — Generate a shareable public link at `digcrate.app/cuts/[id]` Clicking **Publish** calls the API, generates the share URL, and copies it to your clipboard. The button label changes to "Copied!" to confirm. Published Deep Cuts render with the audio player so anyone with the link can listen. Publishing requires a Pro or Team plan. ## Audio player A persistent player bar sits at the bottom of the workspace. It plays YouTube videos and live radio streams without leaving the page. ### YouTube playback When a component contains a playable track or the agent fetches a music video, it triggers playback automatically via the YouTube IFrame API. The player bar shows the track title and artist. A hidden YouTube iframe handles actual playback — you interact with it through the player bar controls only. ### Live radio The `/radio` command searches Radio Browser's catalog of 30,000+ stations and calls `play_radio` to start streaming. The player bar switches to show the station name and a "Live Radio" label. Use `/radio [genre or station name]` — for example `/radio KEXP` or `/radio jazz`. ### Mobile player On mobile, the player bar is a compact mini-player. It hides automatically when the keyboard is open so it does not overlap the input. ## Keyboard shortcuts | Shortcut | Action | | --------- | ------------------------------ | | `Cmd+K` | Focus the sidebar search bar | | `Cmd+N` | Start a new chat session | | `Cmd+B` | Toggle the sidebar open/closed | | `Shift+S` | Open Settings | ## Mobile layout On small screens the workspace switches to a single-column layout. Tap the menu icon in the mobile header to open the sidebar as a full-screen overlay. Tap outside or navigate to a session to close it. Deep Cuts opens as a full-screen view rather than a side panel. Horizontal tabs let you navigate between saved results. A mic button appears above the input on mobile. Tap it to dictate your query using the Web Speech API. The transcript is appended to the input field. The chat input uses a pill shape on mobile with 44px+ touch targets throughout the interface. Digcrate is designed to wrap as an iOS app via Capacitor. The mobile layout is optimized for native-feeling touch interactions.