# TAP -- Full Documentation for AI Agents

> Extended documentation for AI assistants and agents integrating with TAP.
> For a shorter summary, see: https://totalaudiopromo.com/llms.txt

TAP (Total Audio Promo) is professional music PR software for small UK agencies. It is the first music PR tool with a public API and MCP server.

## REST API v1

Base URL: https://totalaudiopromo.com/api/v1
Authentication: Bearer token via `Authorization: Bearer tap_ak_{key}`
Full OpenAPI spec: https://totalaudiopromo.com/api/openapi.json

### Authentication

API keys are workspace-scoped. Format: `tap_ak_{32 hex characters}`.
Keys are SHA-256 hashed before storage. The raw key is shown once at creation.
Create keys in TAP Settings > API Keys, or via POST /api/v1/keys.

Available scopes:
- `contacts:read` -- List and search contacts
- `contacts:write` -- Import and update contacts
- `campaigns:read` -- List and view campaigns and outcomes
- `campaigns:write` -- Create/update campaigns, add contacts, log outcomes
- `validate` -- Email validation
- `enrich` -- AI enrichment
- `briefs:write` -- Accept inbound release briefs from label partners (totalaud.io handoff)
- `*` -- All scopes

### Endpoints (41 total)

#### GET /api/v1/contacts
List contacts for the authenticated workspace.
Query params: page (default 1), limit (default 50, max 200), search, platform_type
Scope: contacts:read
Returns: { contacts, total, page, limit }

#### POST /api/v1/contacts
Import contacts into the workspace. Max 500 per request.
Body: { contacts: [{ email, name?, outlet?, role?, platform_type?, genres?, geographic_scope?, notes? }] }
Headers: X-Idempotency-Key (optional, 1hr TTL)
Query: dry_run=true (validate without inserting)
Scope: contacts:write
Returns: { imported, skipped, invalid, duplicatesInRequest, results }

#### GET /api/v1/contacts/{id}
Get a single contact with full enrichment details.
Scope: contacts:read

#### DELETE /api/v1/contacts/{id}
GDPR-compliant contact erasure.
Scope: contacts:write

#### POST /api/v1/contacts/validate
Validate emails in batch. Max 100 per request.
Body: { emails: ["email@example.com"] }
Scope: validate
Returns: { results: [{ email, valid, confidence, normalised, reason, corrected, suggestedEmail, catchAll, roleBased, disposable, smtpVerified }] }

#### POST /api/v1/contacts/enrich
AI enrichment using Claude Haiku. Max 50 per request.
Body: { contactIds: ["uuid"] }
Scope: enrich
Monthly limits: Free (10), Pro (200), Agency (500)
Returns: { total, enriched, failed, creditsUsed, creditsRemaining, results }

Enrichment adds 14 data points: platform, platform_type, role_detail, genres, coverage_area, contact_method, best_timing, submission_guidelines, pitch_tips, bbc_station, geographic_scope, enrichment_confidence, enrichment_source, enrichment_reasoning.

#### GET /api/v1/campaigns
List campaigns for the authenticated workspace.
Query params: page, limit, status (active/draft/paused/completed), artist_name
Scope: campaigns:read

#### POST /api/v1/campaigns
Create a new PR campaign.
Body: { name (required), artist_name?, release_title?, release_date?, services?, status? }
Scope: campaigns:write

#### GET /api/v1/campaigns/{id}
Get campaign details with stats and recent activity.
Scope: campaigns:read

#### PATCH /api/v1/campaigns/{id}
Partial update of campaign fields.
Scope: campaigns:write

#### GET /api/v1/campaigns/{id}/contacts
List contacts linked to a campaign with pitch status.
Scope: campaigns:read

#### POST /api/v1/campaigns/{id}/contacts
Add existing contacts to a campaign. Max 200 per request.
Scope: campaigns:write

#### GET /api/v1/campaigns/{id}/pitches
List pitch drafts for a campaign.
Scope: campaigns:read

#### POST /api/v1/campaigns/{id}/pitches
Generate AI pitch drafts.
Scope: campaigns:write

#### GET /api/v1/campaigns/{id}/outcomes
List outcomes for a campaign.
Scope: campaigns:read

#### POST /api/v1/campaigns/{id}/outcomes
Log an outcome against a campaign contact.
Scope: campaigns:write

#### GET /api/v1/outcomes
List campaign outcomes with optional filters.
Scope: campaigns:read

#### POST /api/v1/outcomes
Log a campaign outcome for a contact.
Scope: campaigns:write

#### POST /api/v1/release-briefs
Receive an inbound release brief from a label partner (totalaud.io handoff). Idempotent on source_brief_id.
Body: { source_brief_id, source_label_id, source_label_name, artist_name, track_title, assets_url, release_date?, genre?, brief_summary?, callback_url? }
Scope: briefs:write
Returns 201 on first submission, 200 if duplicate.

#### POST /api/v1/release-briefs/{id}/accept
Accept a pending inbound brief. Creates a campaign. Session auth required.

#### POST /api/v1/release-briefs/{id}/decline
Decline a pending inbound brief. Session auth required.

#### GET /api/v1/actions
Get prioritised action queue for active campaigns.
Scope: campaigns:read

#### GET /api/v1/webhooks
List registered webhooks.
Scope: webhooks:read

#### POST /api/v1/webhooks
Register a webhook endpoint.
Scope: webhooks:write

#### DELETE /api/v1/webhooks/{id}
Remove a webhook registration.
Scope: webhooks:write

#### GET /api/v1/keys
List API keys for the workspace. Session auth required.

#### POST /api/v1/keys
Create a new API key. Session auth required.
Body: { name, scopes, agent_name? }
Returns: { key, id } -- raw key shown once only.

#### DELETE /api/v1/keys
Revoke an API key. Session auth required.

### Error Responses

All errors return: { success: false, error: "message" }
- 400: Invalid request body
- 401: Invalid or missing API key
- 403: Insufficient scope
- 404: Resource not found
- 429: Rate limit exceeded (enrichment)
- 500: Server error

## MCP Server

TAP provides a Model Context Protocol server for AI agent integration.
Package: @total-audio/tap-mcp

### Configuration (Claude Code)

```json
{
  "mcpServers": {
    "tap": {
      "command": "npx",
      "args": ["tsx", "packages/tap-mcp/src/index.ts"],
      "env": {
        "TAP_SUPABASE_URL": "your-supabase-url",
        "TAP_SUPABASE_KEY": "your-service-role-key"
      }
    }
  }
}
```

### Tools (49)

[human-gated] = tool is part of the approval/consent flow or explicitly requires human confirmation before action is taken.

campaigns:
- tap_list_campaigns -- List campaigns in the workspace, optionally filtered by status
- tap_get_campaign -- Get campaign details including contacts, outcomes, and pitch stats
- tap_create_campaign -- Create a new campaign in the workspace
- tap_update_campaign -- Update an existing campaign (name, status, dates, goal, services)
- tap_suggest_contacts -- Get AI-scored contact suggestions for a campaign based on warmth, genre overlap, response rate, and past outcomes
- tap_add_contact_to_campaign -- Add a contact to a campaign (creates a campaign_contacts link)
- tap_campaign_memory -- Get or set campaign learnings/memory

contacts:
- tap_list_contacts -- List contacts in the workspace with optional filters
- tap_search_contacts -- Search contacts by name, outlet, genre, or BBC station
- tap_contact_insights -- Get relationship insights for a contact (warmth, response rate, outcomes)
- tap_create_contact -- Create a new contact in the workspace
- tap_update_contact -- Update an existing contact in the workspace

artists:
- tap_create_artist -- Create a new artist in the workspace. Returns the artist ID for use in tap_create_campaign.
- tap_list_artists -- List artists in the workspace. Includes archived flag.

pitches:
- tap_draft_pitch -- Generate a complete AI-drafted pitch for a contact within a campaign. Returns subject, body, and variants.
- tap_propose_send [human-gated] -- Propose that a drafted pitch be sent. Drops the pitch into the human approval queue with a reason and confidence score; never sends directly.

pitch-queue:
- tap_list_pitch_drafts -- List all pitch drafts for a campaign. Returns contact name, draft count, status, and variants.
- tap_batch_draft_pitches [human-gated] -- Generate AI pitch drafts for multiple contacts in a campaign. Creates variants for review. Drafts are NOT sent — agents draft, humans send.
- tap_queue_pitch_review [human-gated] -- Mark pitches as ready for human review. Updates pitch_status to "queued". Agents draft, humans send.

outcomes:
- tap_get_outcomes -- List outcomes for a campaign. Returns up to 200 most recent.
- tap_update_outcome -- Correct or annotate a previously logged outcome.
- tap_log_outcome -- Log a campaign outcome for a contact
- tap_get_action_queue -- Return today's prioritised action queue (follow-ups, stale contacts, pending pitches)

analysis:
- tap_analyse_campaign -- Analyse a campaign — returns contacts, pitch stats, outcomes, response rates, and relationship metrics in one call
- tap_suggest_next_actions -- Suggest next actions for a campaign based on pitch status, outcomes, and relationship data
- tap_workspace_overview -- Get a high-level overview of the workspace: active campaigns, contact counts, recent outcomes, and overall performance

batch:
- tap_batch_enrich -- Enrich multiple contacts at once (up to 20). Queues AI enrichment for each contact and returns results with confidence scores.
- tap_batch_import -- Import contacts from a JSON array. Parses, deduplicates against existing contacts, and inserts new ones. Returns import summary.
- tap_batch_validate -- Validate email addresses for multiple contacts. Checks MX records, format, and deliverability.

approvals:
- tap_get_approval_status [human-gated] -- Get the current status of an agent session, including any pending approval. Use to poll after tap_request_approval.
- tap_request_approval [human-gated] -- Request human approval before proceeding. Use when you have drafted pitches or prepared a contact list that needs review. The agent session pauses until a human approves or rejects.

consent:
- tap_set_send_consent [human-gated] -- Grant send consent for the current workspace. Idempotent: if consent is already granted, returns the existing record without overwriting.

outreach:
- tap_list_pending_executions [human-gated] -- List pending multi-channel sequence executions awaiting human approval. Joined to contact and campaign for context.
- tap_create_sequence -- Create a new multi-channel outreach sequence for a campaign. Returns the sequence id.
- tap_queue_execution [human-gated] -- Queue a single sequence step execution against a campaign contact. Always requires human approval before dispatch.
- tap_approve_execution [human-gated] -- Approve a pending sequence execution. Requires the workspace to have send_consent_at set. Cron will dispatch after approval.
- tap_get_channel_outcomes -- List recorded channel outcomes (sent, opened, replied, etc) joined to contact and campaign.

assets:
- tap_list_campaign_assets -- List Drive-synced assets for a campaign, with optional kind filter (audio, image, document, video, other).
- tap_get_asset_url -- Get viewer and embed URLs for a campaign asset.

monitor:
- tap_list_radio_plays -- List radio plays detected by TAP, joined with station and reference track. Workspace-scoped.
- tap_enrol_reference_track -- Enrol a track for radio-plays tracking. Inserts a reference track with a PENDING_BACKFILL fingerprint.
- tap_get_play_summary -- Summary of radio plays for a campaign: total plays, distinct stations, peak week, latest play.

skills:
- tap_list_skills -- List every skill visible to this workspace — TAP defaults overlaid with any workspace forks.
- tap_get_skill -- Fetch a single skill in full — manifest, tools, permissions, and the resolved markdown body.
- tap_run_skill -- Execute a workspace skill. Skills can draft pitches, fact-check copy, and prepare reports — but never approve or send anything.
- tap_fork_skill -- Create or update a workspace-owned override for a default skill. Pass body=null to restore the TAP default.
- tap_get_invocation -- Fetch a single skill invocation audit row by id. Returns inputs, outputs, error, duration, tokens, confidence.
- tap_get_approval_queue [human-gated] -- Read-only view of pitch drafts awaiting human review. Approving or sending is a per-message human action in the TAP UI. Agents draft, humans send.
- tap_get_outreach_queue -- Unified read across pitch drafts and sequence executions. Wider than the approval queue — shows full outreach pipeline state. Read-only.

### Resources (3)

- tap://campaigns -- Browse all campaigns as JSON (up to 100, ordered by created_at desc)
- tap://contacts -- Browse all contacts as JSON (up to 100, ordered by name asc)
- tap://artists -- Browse all artists as JSON (up to 100, ordered by name asc)

## Human Approval Boundary

TAP can analyse, suggest, draft, and queue. TAP never auto-sends without explicit human approval.

Agent capabilities:
- Analyse campaigns and contacts
- Suggest contacts and next actions
- Draft and queue pitches for review
- Propose sends with rationale and confidence score
- Log outcomes and update records
- Run skills (fact-check, copy review, WARM reports)

Agent restrictions:
- Cannot approve or dispatch a pitch without a human confirming in the TAP UI
- Cannot auto-send outreach sequences without tap_approve_execution + send_consent_at set by the workspace owner
- Cannot override judgement or restructure campaigns without consent

## Pricing

- Freelancer: GBP 39/month -- 500 enrichments, unlimited pitches, 10 campaigns. 14-day trial.
- Agency: GBP 249/month -- unlimited enrichments, unlimited campaigns, 5 team members, the agent surface (scoped API keys, MCP server, skills), white-label reports. 14-day trial.
- Enterprise: custom quote -- everything in Agency, unlimited team members, concierge onboarding.
- No free tier for new sign-ups.

## Product Family

- TAP (totalaudiopromo.com): Professional music PR software for agencies
- totalaud.io: Label-side workspace for roster planning, release briefs, and handoff into TAP

## Quick Start

1. Sign up at https://totalaudiopromo.com/signup
2. Go to Settings > API Keys
3. Create a key with desired scopes
4. Make your first request:

curl https://totalaudiopromo.com/api/v1/contacts \
  -H "Authorization: Bearer tap_ak_your_key_here"

## Company

Total Audio Promo Ltd, United Kingdom
Founded by Chris Schofield, 5+ years in music promotion
GDPR compliant, privacy-first
Contact: info@totalaudiopromo.com