API Endpoints

Full reference for every ArtistGuard API endpoint.

Base URL: https://v2-prod-api.artistguard.app

All endpoints use JSON. Authentication required on all routes except public auth endpoints. See Authentication.

Artists

GET    /api/v1/artists                                      List all monitored artists
GET    /api/v1/artists/summary                              Artists with stats and 7-day change counts
GET    /api/v1/artists/{id}                                 Get one artist
GET    /api/v1/artists/{id}/snapshot                        Latest snapshot (stats, bio, top tracks, socials)
GET    /api/v1/artists/{id}/snapshot-history                Follower/listener history (query: ?days=30)
GET    /api/v1/artists/{id}/changes                         Change history for this artist
GET    /api/v1/artists/{id}/releases                        Full discography
GET    /api/v1/artists/{id}/releases/{release_id}           Single release
GET    /api/v1/artists/{id}/releases/{release_id}/tracks    Track list for a release
DELETE /api/v1/artists/{id}                                 Stop monitoring this artist
GET    /api/v1/artists/search?q={query}                     Search Spotify catalog
GET    /api/v1/artists/lookup?url={spotifyUrl}              Resolve a Spotify artist URL to an ID

Example response (list artists)

[
  {
    "id": "ma_abc123",
    "spotify_id": "6eUKZXaKkcviH0Ku9w2n3V",
    "name": "Artist Name",
    "active": true,
    "last_checked_at": "2026-03-07T10:00:00Z"
  }
]

Artist Verification

Before monitoring an artist, ownership must be verified. Business plan customers can use instant verification.

POST /api/v1/verify/start              Start a standard verification session
GET  /api/v1/verify/{session_id}       Poll session status
GET  /api/v1/verify/pending            Get your current pending session
POST /api/v1/verify/instant            Instant verify (Business only)

Instant verify body

{ "spotify_id": "6eUKZXaKkcviH0Ku9w2n3V" }

Instant verification bypasses the standard ownership challenge. Only available on the Business plan. Returns the verified artist immediately.

Changes

GET /api/v1/changes                  All changes across your organization, newest first
GET /api/v1/changes/stats/daily      Daily change counts (query: ?days=30)

Param	Type	Description
`limit`	int	Max results (default 50, max 100)
`offset`	int	Pagination offset

Destinations

Destinations are named delivery targets (Discord webhook, Slack webhook, email address, etc.). Alert rules reference a destination by ID.

GET    /api/v1/org/destinations              List all destinations
POST   /api/v1/org/destinations              Create a destination
PATCH  /api/v1/org/destinations/{id}         Update a destination
DELETE /api/v1/org/destinations/{id}         Delete a destination
POST   /api/v1/org/destinations/{id}/test    Send a test message

Create/update body

{
  "name": "Team Discord",
  "type": "discord",
  "config": {
    "url": "https://discord.com/api/webhooks/..."
  }
}

type: discord, slack, email, or webhook

Config keys by type:

Type	Config fields
`discord`	`url` (webhook URL)
`slack`	`url` (webhook URL)
`email`	`address`
`webhook`	`url`

Alert Rules

GET    /api/v1/org/alerts           List all rules
POST   /api/v1/org/alerts           Create a rule
PATCH  /api/v1/org/alerts/{id}      Update a rule
DELETE /api/v1/org/alerts/{id}      Delete a rule

Create/update body

{
  "name": "Critical alerts",
  "destination_id": "dest_abc123",
  "min_severity": "critical",
  "event_types": [],
  "artist_filter": null,
  "active": true
}

destination_id: ID of an existing destination

min_severity: critical, warning, or info

event_types: array of change type strings, empty array means all types

artist_filter: monitored artist ID or null for all artists

Outgoing Webhooks

Outgoing webhooks deliver a signed HTTP POST to your endpoint for every change event.

GET    /api/v1/org/webhooks                      List webhooks
POST   /api/v1/org/webhooks                      Create a webhook
PATCH  /api/v1/org/webhooks/{id}                 Update a webhook
DELETE /api/v1/org/webhooks/{id}                 Delete a webhook
POST   /api/v1/org/webhooks/{id}/rotate-secret   Rotate signing secret
POST   /api/v1/org/webhooks/{id}/test            Send a test event

Organization

GET    /api/v1/org                               Get org details and plan info
PATCH  /api/v1/org                               Update org name
GET    /api/v1/org/members                       List members with roles
PATCH  /api/v1/org/members/{user_id}             Update a member's role
DELETE /api/v1/org/members/{user_id}             Remove a member
GET    /api/v1/org/invitations                   List pending invitations
POST   /api/v1/org/invitations                   Send email invite
DELETE /api/v1/org/invitations/{id}              Revoke invite
POST   /api/v1/org/leave                         Leave the organization

Account

GET    /api/v1/auth/me                   Current user profile
PATCH  /api/v1/auth/me                   Update name or email
POST   /api/v1/auth/logout               Clear session cookie
GET    /api/v1/auth/sessions             Active sessions list
DELETE /api/v1/auth/sessions/{id}        Revoke one session

API Keys

GET    /api/v1/org/api-keys          List all keys (prefix and metadata only)
POST   /api/v1/org/api-keys          Create a key (full key returned once)
DELETE /api/v1/org/api-keys/{id}     Revoke a key (immediate)
POST   /api/v1/org/api-terms/accept  Accept API terms of use

Create body

{ "name": "CI pipeline" }

Create response (full key shown only here, never again)

{
  "id": "key_abc123",
  "name": "CI pipeline",
  "key": "ag_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "ag_live_xxxx",
  "created_at": "2026-03-07T10:00:00Z"
}

API access requires Pro or Business plan.

Health (public, no auth)

GET /health

{
  "data": {
    "status": "healthy",
    "timestamp": "2026-03-24T08:28:30Z",
    "version": "[email protected]",
    "uptime": "44h38m15s"
  }
}

PreviousAuthentication NextManaging API Keys