{
  "$schema": "https://pulse.studiosphere.space/.well-known/pulse/agent-journey.schema.json",
  "version": "1.0.0",
  "service": "StudioSphere Pulse",
  "updated": "2026-07-03",
  "goal": "Enable autonomous agents to discover Pulse, connect with a human-funded API key, estimate cost, analyze authorized audio, and poll results without Stripe Checkout.",
  "discovery": {
    "product": "https://pulse.studiosphere.space",
    "mcp_endpoint": "https://mcp.studiosphere.space/mcp",
    "mcp_with_api_key": "https://mcp.studiosphere.space/mcp?api_key=YOUR_PULSE_API_KEY",
    "connect": "https://pulse.studiosphere.space/connect",
    "for_agents": "https://pulse.studiosphere.space/for-agents",
    "llms_txt": "https://pulse.studiosphere.space/llms.txt",
    "llms_full_txt": "https://pulse.studiosphere.space/llms-full.txt",
    "mcp_manifest": "https://pulse.studiosphere.space/.well-known/mcp/server.json",
    "registry_name": "space.studiosphere/pulse",
    "registry_version": "1.0.2"
  },
  "preconditions": {
    "human_setup_once": [
      "Create a Pulse account and fund banked tokens (token packs) or use an existing paid balance.",
      "Configure the MCP client with the API key in the connection URL query parameter.",
      "Give the agent instructions that include a reusable rights-attestation policy for the user's authorized audio scope."
    ],
    "required_secret": "PULSE_API_KEY",
    "auth_method": "query_param_at_mcp_init",
    "auth_note": "The API key must be present when the MCP session is initialized (?api_key=sk_pulse_...). Per-request Authorization headers are not supported in v1.0."
  },
  "analysis_outputs_v1": ["bpm", "key", "waveform"],
  "mcp_workflow_tools": [
    "get_token_balance",
    "estimate_cost",
    "analyze_track",
    "get_job_status",
    "list_token_packs",
    "purchase_token_pack",
    "start_trial",
    "request_payment_link"
  ],
  "paths": {
    "funded_autonomous": {
      "description": "Preferred path when the human has funded banked tokens and configured the MCP client with an API key.",
      "steps": [
        {
          "order": 1,
          "tool": "get_token_balance",
          "purpose": "Confirm banked_tokens > 0 before spending."
        },
        {
          "order": 2,
          "tool": "estimate_cost",
          "purpose": "Free price quote. Always call before analyze_track.",
          "inputs": ["audio_url", "tools"]
        },
        {
          "order": 3,
          "human_or_policy": "rights_attestation",
          "purpose": "Confirm lawful access. One batch confirmation can cover a folder, playlist, project, or catalog scope."
        },
        {
          "order": 4,
          "tool": "analyze_track",
          "purpose": "Spend banked tokens and enqueue analysis.",
          "inputs": ["audio_url", "tools", "job_estimate_id", "attestation_confirmed"],
          "requires_api_key": true
        },
        {
          "order": 5,
          "tool": "get_job_status",
          "purpose": "Poll until status is completed, partial, failed, or expired.",
          "inputs": ["job_id"]
        }
      ]
    },
    "trial": {
      "description": "One short URL analysis for first-time users without an account. Not suitable for repeated autonomous batch work.",
      "steps": ["start_trial", "estimate_cost", "analyze_track", "get_job_status"]
    },
    "checkout": {
      "description": "Human-in-the-loop Stripe Checkout. One-time checkout has a $0.50 minimum; banked-token usage has no minimum per job.",
      "steps": ["estimate_cost", "request_payment_link", "get_job_status"],
      "not_autonomous": true
    }
  },
  "spend_policy_example": {
    "max_tokens_per_job": 50,
    "max_tokens_per_session": 500,
    "allowed_tools": ["bpm", "key", "waveform"],
    "batch_attestation_scope": "User confirmed lawful access to tracks in the requested playlist/folder on 2026-07-03."
  },
  "errors": {
    "no_api_key": {
      "meaning": "MCP session was not initialized with ?api_key=.",
      "recovery": "Reconnect MCP with https://mcp.studiosphere.space/mcp?api_key=sk_pulse_... or call start_trial for one short trial."
    },
    "unauthorized": {
      "meaning": "Invalid or revoked API key at MCP init.",
      "recovery": "Ask the human to verify the key at /connect or rotate at /account."
    },
    "insufficient_balance": {
      "meaning": "Banked tokens are too low for the estimate.",
      "recovery": "Call list_token_packs then purchase_token_pack and present payment_url to the human, or stop."
    },
    "below_minimum_charge": {
      "meaning": "One-time checkout minimum is $0.50.",
      "recovery": "Use funded banked tokens instead, bundle more tools, or analyze longer audio."
    },
    "attestation_required": {
      "meaning": "analyze_track or request_payment_link called without attestation_confirmed=true.",
      "recovery": "Confirm rights with the human or apply the pre-approved batch policy."
    },
    "trial_limit_reached": {
      "meaning": "A trial was already started recently from this network.",
      "recovery": "Use a funded API key or create an account at /signup."
    }
  }
}