# 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's the first music PR tool with a public API and MCP server -- no competitor offers programmatic access.

## 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 contacts
- `validate` -- Email validation
- `enrich` -- AI enrichment
- `*` -- All scopes

### Endpoints

#### 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 }

#### 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/keys
List API keys for the workspace. Session auth required (not API key).
Returns: { keys: [{ id, name, agent_name, scopes, key_prefix, last_used_at, created_at, revoked_at }] }

#### 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.
Body: { keyId }
Returns: { revoked: true, keyId }

### 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 (10)

Campaign tools:
- tap_list_campaigns -- List campaigns with optional status filter
- tap_get_campaign -- Get campaign details with contact counts and pitch stats

Contact tools:
- tap_list_contacts -- List contacts with filters (status, genre, BBC-only, search)
- tap_search_contacts -- Search contacts by name, outlet, genre, or BBC station
- tap_contact_insights -- Get enrichment and relationship insights for a contact

Pitch tools:
- tap_draft_pitch -- Generate AI-drafted pitches (subject, body, variants). Accepts campaign_id, contact_id, tone (professional/casual/enthusiastic), key_hook.

Outcome tools:
- tap_log_outcome -- Log campaign outcomes: no_response, opened, replied_positive, replied_negative, added_to_playlist, interview_booked, coverage, declined, other
- tap_get_action_queue -- Get today's prioritised action queue (follow-ups, stale contacts, pending pitches)

### Resources (3)

- tap://campaigns -- Browse all campaigns as JSON
- tap://contacts -- Browse all contacts as JSON
- tap://artists -- Browse all artists as JSON

## Pricing

- Free: GBP 0/month -- 10 enrichments, 3 pitches, 2 campaigns, 25 contacts
- Pro: GBP 19/month (early access) -- 200 enrichments, unlimited pitches, 10 campaigns
- Agency: GBP 79/month (early access) -- 500 enrichments, unlimited campaigns, 5 team members, API access, white-label reports

## Product Family

- TAP (totalaudiopromo.com): Professional music PR software for agencies
- totalaud.io: Calm workspace for independent artists planning releases

## 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: chris@totalaudiopromo.com