// DEVELOPER DOCUMENTATION · v1.2

Icon Agents API Reference

The execution-native AI agent stack for the music business. Full SDK and REST API. Your grk_ key unlocks chat, intel, config, and metered LLM completions.

Quick Start

JavaScript — npm import

import { IconAgent } from 'https://www.iconbreaking.com/iconagents/sdk/iconagents-sdk.mjs';

const agent = new IconAgent({
  apiKey: 'grk_YOUR_KEY',
  rail: 'themusicindustry.ai'
});

// Talk to the Rollout Agent
const reply = await agent.ask('Week 4 of my rollout — what do I do?');

// Get today's intel
const intel = await agent.getIntel({ date: '2026-07-24' });

// Configure your pillars
await agent.configurePillars({
  'Capital & Deals': 25,
  'AI/Music': 20,
  'Web3/Blockchain': 15,
  'Industry Structure': 25,
  'Top Signal': 15
});

// Chat with a specific skill
const scorecard = await agent.skills.chat('scorecard', 'Score my readiness');

Authentication

All API requests require a grk_ API key, provisioned when you join the Founding 100. Pass it as a Bearer token:

Authorization: Bearer grk_YOUR_KEY

Self-serve members ($7/$97) get read-only intel access. Full execution and chat requires a Founding 100 seat. Get your API key →

Available Skills

Skills are the agent templates. Each is a specialized vertical with its own system prompt, protocol, and intent routing.

Skill ID	Name	Status	Description
rollout	Rollout Agent	● LIVE	11-week music release protocol
daily-intel	Daily Intel Agent	● LIVE	Five-pillar market intelligence briefs
scorecard	Scorecard Agent	● LIVE	Masterclass registrant readiness scoring
discovery	Discovery Agent	SOON	Qualify inbound leads by phone
sales	Sales Agent	SOON	Close cycle execution
consulting	Consulting Agent	SOON	Scanner briefs and strategic review

POST /api/iba/rollout-chat

POST /api/iba/rollout-chat ● LIVE

Create or continue a rollout-agent chat session. The agent maintains session memory across turns.

Request Body

Parameter	Type	Required	Description
message	string	YES	The user's message to the agent
session_id	string	no	Session ID for multi-turn memory. Auto-generated if omitted.
surface	string	no	Origin surface: 'web', 'workspace', 'discord', 'sdk', 'mcp'
email	string	no	User email for personalization

Response

{ "ok": true, "reply": "...", "session_id": "...", "rail": "deepseek" }

POST /api/iba/skill-chat

POST /api/iba/skill-chat?skill={skill_id} ● LIVE

Chat with a specific registered skill. Uses the generalized Skill handler with intent classification and D1 session memory.

Request Body

Parameter	Type	Required	Description
message	string	YES	The user's message
session_id	string	no	Session ID for memory continuity
skill	string	no	Skill ID (rollout, daily-intel, scorecard). Default: rollout
email	string	no	User email

GET /api/v1/intel/{client}/{date}

GET /api/v1/intel/{client_slug}/{date} ● LIVE

Retrieve a daily intel brief by client slug and date. Returns verdict + full markdown brief.

Response

{
  "ok": true,
  "brief": {
    "id": "...",
    "date": "2026-07-24",
    "verdict": "UMG's catalog deal signals...",
    "signal_count": 15,
    "delivery_status": "delivered"
  },
  "content": { "brief_markdown": "## Capital & Deals\\n..." }
}

GET /api/v1/intel/{client}/latest

GET /api/v1/intel/{client_slug}/latest ● LIVE

Get the most recent intel brief for a client. Includes verdict and full markdown.

GET /api/v1/intel/{client}

GET /api/v1/intel/{client_slug}?limit={n} ● LIVE

List recent intel briefs. Default limit: 14.

POST /api/v1/config/{client}/pillars

POST /api/v1/config/{client_slug}/pillars ● LIVE

Update pillar weights for a client's vertical. Weights should sum to ~100 (80-120 accepted).

Request Body

{
  "weights": {
    "Capital & Deals": 25,
    "AI/Music": 20,
    "Web3/Blockchain": 15,
    "Industry Structure": 25,
    "Top Signal": 15
  }
}

GET /api/v1/config/{client}/pillars

GET /api/v1/config/{client_slug}/pillars ● LIVE

Get current pillar configuration for a client.

GET /api/v1/tokens/balance

GET /api/v1/tokens/balance ● LIVE

Check prepaid token balance and usage for the authenticated grk_ key.

POST /api/v1/tokens/buy

POST /api/v1/tokens/buy ● LIVE

Purchase a prepaid token pack ($50 / $100 / $200). Returns a Stripe checkout URL.

Request Body

Parameter	Type	Required	Description
pack_id	string	YES	Pack ID: 'pack_50', 'pack_100', 'pack_200'

POST /api/v1/chat/completions

POST /api/v1/chat/completions ● LIVE

Metered LLM completion via the GRK relay. Two-tier: Ollama pool (owned) → DeepSeek (billed overflow). Client price pegged to DeepSeek rate × markup. Usage metered through Stripe.

OpenAI-compatible request/response format. Use your grk_ key as the Bearer token.

POST /api/v1/mcp

POST /api/v1/mcp ● LIVE

JSON-RPC 2.0 endpoint for Model Context Protocol. Exposes all Icon Agent tools to external AI tools (Claude, Codex, Gemini, etc.).

Available MCP Tools

Tool	Description
iconagent_chat	Chat with any registered skill
iconagent_intel	Get intel brief by date
iconagent_intel_latest	Get latest intel brief
iconagent_intel_list	List recent intel briefs
iconagent_configure_pillars	Update pillar weights
iconagent_token_balance	Check token balance
iconagent_receipts	List delivery receipts

Claude Code MCP Config

{
  "mcpServers": {
    "iconagents": {
      "type": "http",
      "url": "https://themusicindustry.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer grk_YOUR_KEY" }
    }
  }
}

// FOUNDING 100 ACCESS

Full API access — chat, intel, config, metered completions, and MCP — requires a Founding 100 seat. Self-serve members get read-only intel.

Apply for Founding 100 →