API Reference Overview

The Soundcheck api-events service provides RESTful endpoints for managing events, teams, setlists, and more. OpenAPI source of truth: docs/openapi/soundcheck.json (from npm run openapi:emit in api-events/).

Base URL

Environment	Base URL
Development	`http://localhost:4000`
Production	`https://api.soundchecklive.io`

Authentication

All API requests require authentication via Clerk JWT tokens.

curl -H "Authorization: Bearer <token>" \
  https://api.soundchecklive.io/api/v1/users/me

const response = await fetch('https://api.soundchecklive.io/api/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});
const user = await response.json();

import requests

response = requests.get(
    'https://api.soundchecklive.io/api/v1/users/me',
    headers={'Authorization': f'Bearer {token}'}
)
user = response.json()

req, _ := http.NewRequest("GET", "https://api.soundchecklive.io/api/v1/users/me", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)

See Authentication for details.

API Services

Users

Manage user accounts, profiles, and push notification targets.

GET    /api/v1/users                              # List users
POST   /api/v1/users                              # Create user
GET    /api/v1/users/me                           # Get current user
GET    /api/v1/users/:id                          # Get user by ID
PUT    /api/v1/users/:id                          # Update user
DELETE /api/v1/users/:id                          # Delete user
GET    /api/v1/users/me/push-targets              # List push targets
POST   /api/v1/users/me/push-targets              # Register push target
PATCH  /api/v1/users/me/push-targets/:id          # Update push target
DELETE /api/v1/users/me/push-targets/:id          # Delete push target
POST   /api/v1/users/stripe/connect/statuses/bulk # Bulk get member Connect statuses
GET    /api/v1/users/:id/stripe/connect/status    # Get member Connect status
GET    /api/v1/users/:id/stripe/connect/link      # Get member onboarding or dashboard link
POST   /api/v1/users/:id/stripe/connect/payouts-session # Create embedded payouts session

Organizations

Manage organizations, members, and positions.

GET    /api/v1/organizations                                # List organizations
POST   /api/v1/organizations                                # Create organization
GET    /api/v1/organizations/:id                            # Get organization
PUT    /api/v1/organizations/:id                            # Update organization
DELETE /api/v1/organizations/:id                            # Schedule deletion (30-day grace)
POST   /api/v1/organizations/:id/deletion                   # Schedule deletion; returns date + renewal status
POST   /api/v1/organizations/:id/restore                    # Cancel a scheduled deletion
POST   /api/v1/organizations/:id/members                    # Add member
DELETE /api/v1/organizations/:id/members/:member_id         # Remove member
GET    /api/v1/organizations/:id/positions                  # List positions
POST   /api/v1/organizations/:id/positions                  # Create position
PUT    /api/v1/organizations/:id/positions/:pos_id          # Update position
DELETE /api/v1/organizations/:id/positions/:pos_id          # Delete position
POST   /api/v1/organizations/:id/positions/bulk             # Bulk enable positions

Events

Manage events (gigs), schedules, attachments, and team assignments.

GET    /api/v1/events                              # List events
POST   /api/v1/events                              # Create event
GET    /api/v1/events/:id                          # Get event
PUT    /api/v1/events/:id                          # Update event
DELETE /api/v1/events/:id                          # Delete event
POST   /api/v1/events/:id/archive                  # Archive event
POST   /api/v1/events/:id/unarchive                # Unarchive event
POST   /api/v1/events/:id/members                  # Manage event members
GET    /api/v1/events/:id/schedule                 # Get schedule items
POST   /api/v1/events/:id/schedule                 # Create schedule items
PUT    /api/v1/events/:id/schedule                 # Upsert schedule items
GET    /api/v1/events/:id/attachments              # List attachments
POST   /api/v1/events/:id/attachments              # Upload attachment
GET    /api/v1/events/:id/attachments/:att_id      # Get attachment
PUT    /api/v1/events/:id/attachments/:att_id      # Update attachment
DELETE /api/v1/events/:id/attachments/:att_id      # Delete attachment
GET    /api/v1/events/:id/setlists                 # Get event setlists

Invitations

Manage event invitations.

POST   /api/v1/invitations                                    # Create bulk invitations
GET    /api/v1/invitations/:id                                # Get invitation
POST   /api/v1/invitations/:id/accept                         # Accept invitation
POST   /api/v1/invitations/:id/decline                        # Decline invitation
GET    /api/v1/users/:id/invitations                          # Get user's invitations
PUT    /api/v1/events/:id/invitations/bulk-process            # Bulk process invitations

Calllists

Reusable team templates for quick event staffing.

GET    /api/v1/calllists                           # List calllists
POST   /api/v1/calllists                           # Create calllist
GET    /api/v1/calllists/:id                       # Get calllist
PUT    /api/v1/calllists/:id                       # Update calllist
DELETE /api/v1/calllists/:id                       # Delete calllist
POST   /api/v1/calllists/:id/apply-to-event        # Apply to event

Preset Teams

Saved team configurations for recurring event types.

GET    /api/v1/preset-teams                        # List preset teams
POST   /api/v1/preset-teams                        # Create preset team
GET    /api/v1/preset-teams/:id                    # Get preset team
PUT    /api/v1/preset-teams/:id                    # Update preset team
DELETE /api/v1/preset-teams/:id                    # Delete preset team
POST   /api/v1/preset-teams/:id/apply-to-event     # Apply to event

Setlists

Manage setlists and their song arrangements.

GET    /api/v1/setlists                            # List setlists
POST   /api/v1/setlists                            # Create setlist
GET    /api/v1/setlists/:id                        # Get setlist
PUT    /api/v1/setlists/:id                        # Update setlist
DELETE /api/v1/setlists/:id                        # Delete setlist

Songs

Manage the song library and attachments (sheet music, charts).

GET    /api/v1/songs                               # List songs
POST   /api/v1/songs                               # Create song
GET    /api/v1/songs/:id                           # Get song
PUT    /api/v1/songs/:id                           # Update song
DELETE /api/v1/songs/:id                           # Delete song
GET    /api/v1/songs/:id/attachments               # List attachments
POST   /api/v1/songs/:id/attachments               # Upload attachment
GET    /api/v1/songs/:id/attachments/:att_id       # Get attachment
PUT    /api/v1/songs/:id/attachments/:att_id       # Update attachment
DELETE /api/v1/songs/:id/attachments/:att_id       # Delete attachment
POST   /api/v1/songs/attachments/bulk              # Bulk fetch attachments

Positions

Global position definitions (instruments, roles).

GET    /api/v1/positions                           # List default positions

Performance Folders

Personal folders for performers containing their materials for an event.

GET    /api/v1/events/:id/performance-folder           # Get folder
PUT    /api/v1/events/:id/performance-folder           # Upsert folder
DELETE /api/v1/events/:id/performance-folder           # Delete folder
GET    /api/v1/events/:id/performance-folder/exists    # Check if exists

Lead Requests

Manage booking inquiries and leads.

GET    /api/v1/lead-requests                       # List lead requests
POST   /api/v1/lead-requests                       # Create lead request
PUT    /api/v1/lead-requests/:id                   # Update lead request
DELETE /api/v1/lead-requests/:id                   # Delete lead request

Finance

Track event finances, income, expenses, and member payments.

GET    /api/v1/events/:id/finances                     # List finance line items
POST   /api/v1/events/:id/finances                     # Create finance line item
GET    /api/v1/events/:id/finances/:item_id            # Get finance line item
PUT    /api/v1/events/:id/finances/:item_id            # Update finance line item
DELETE /api/v1/events/:id/finances/:item_id            # Delete finance line item
GET    /api/v1/events/:id/finances/summary             # Get event finance summary
GET    /api/v1/events/:id/performers/payments          # List performer payments
PUT    /api/v1/events/:id/performers/:inv_id/payment   # Update payment status
GET    /api/v1/organizations/:id/finances              # Get org finance metrics
GET    /api/v1/events/:id/ledger                       # List event ledger items
POST   /api/v1/events/:id/ledger                       # Create a ledger item
POST   /api/v1/events/:id/ledger/pay                   # Batch-pay unpaid event payables
POST   /api/v1/events/:id/ledger/:ledger_item_id/pay   # Pay one ledger item
POST   /api/v1/events/:id/ledger/:ledger_item_id/reverse # Reverse latest manual payment
POST   /api/v1/events/:id/ledger/:ledger_item_id/void  # Void a ledger item
GET    /api/v1/organizations/:id/ledger                # List organization ledger items
GET    /api/v1/users/me/ledger                         # List current user's ledger items

Stripe payout requests can return per-item results for batch payments: success, processing, requires_action, or error. When requires_action is returned, the client should complete the Stripe next-action flow and then refresh the ledger item.

Payments

Configure organization payment settings and Stripe payout funding methods.

GET    /api/v1/organizations/:id/payments/accounts                       # Get org Stripe account status
GET    /api/v1/organizations/:id/payments/currencies                     # List supported currencies
GET    /api/v1/organizations/:id/payments/methods                        # List supported payment methods
GET    /api/v1/organizations/:id/payments/settings                       # Get currency and platform fee settings
PATCH  /api/v1/organizations/:id/payments/settings                       # Update currency and fee settings
POST   /api/v1/organizations/:id/payments/setup-intent                   # Create setup intent for funding method
GET    /api/v1/organizations/:id/payments/funding-methods                # List saved payout funding methods
POST   /api/v1/organizations/:id/payments/funding-methods/default        # Set default payout funding method
PATCH  /api/v1/organizations/:id/payments/funding-methods/:payment_method_id # Rename funding method
DELETE /api/v1/organizations/:id/payments/funding-methods/:payment_method_id # Remove funding method
POST   /api/v1/organizations/:id/integrations/stripe/connect/link        # Get org Connect onboarding link
GET    /api/v1/organizations/:id/integrations/stripe/connect/status      # Get org Connect status

Card-funded member payouts use the configured platform fee percentage. ACH-funded payouts use a 0% platform fee because Soundcheck absorbs ACH fees.

Notifications

Send and manage notifications (email, SMS, push).

GET    /api/v1/notifications                       # List notifications
POST   /api/v1/notifications                       # Send bulk notifications
GET    /api/v1/notifications/:id                   # Get notification
PUT    /api/v1/notifications/:id                   # Update notification
POST   /api/v1/notifications/email                 # Send email
POST   /api/v1/notifications/sms                   # Send SMS
GET    /api/v1/notifications/event/:id             # Get event notifications
POST   /api/v1/notifications/event/:id             # Send event notifications

Subscriptions

Manage subscription plans and billing.

GET    /api/v1/subscriptions                       # List subscriptions
GET    /api/v1/subscriptions/plans                 # Get available plans
POST   /api/v1/subscriptions/checkout              # Create checkout session
POST   /api/v1/subscriptions/create                # Create subscription
GET    /api/v1/subscriptions/:id                   # Get subscription
PUT    /api/v1/subscriptions/:id                   # Update subscription
POST   /api/v1/subscriptions/:id/cancel            # Cancel subscription

Wrapped

Annual statistics and year-in-review data.

GET    /api/v1/users/me/wrapped                    # Current user's wrapped
GET    /api/v1/users/:id/wrapped                   # User's wrapped
GET    /api/v1/organizations/:id/wrapped           # Organization's wrapped

Response format

Success response

{
  "data": {
    "id": "evt_123",
    "title": "Summer Concert",
    "date": "2024-06-15T19:00:00Z"
  }
}

Error response

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Event not found",
  "details": ""
}

Status codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Pagination

List endpoints support pagination via query parameters:

GET /api/v1/events?limit=20&offset=0

Common pagination parameters:

Parameter	Description
`limit`	Maximum items to return (default varies by endpoint)
`offset`	Number of items to skip

Customer, inventory, sponsor, organization venue, user, organization member, group, group member, availability request, and user engagement lists default to 10,000 rows and cap each request at 10,000 rows. Venue search defaults to 50 rows and has the same 10,000-row maximum. Existing smaller limits on other endpoints are unchanged. These lists apply pagination in the database. To read a complete collection, request a fixed page size (for example, 500), increment offset by that size, and stop when a response contains fewer rows than requested. Keep filters the same across requests. Unique ID tie-breakers make ordering deterministic for unchanged data; concurrent inserts or deletes can still shift offset pages.

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

API Reference Overview

Base URL

Authentication

API Services

Users

Organizations

Events

Invitations

Calllists

Preset Teams

Setlists

Songs

Positions

Performance Folders

Lead Requests

Finance

Payments

Notifications

Subscriptions

Wrapped

Response format

Success response

Error response

Status codes

​Base URL

​Authentication

​API Services

​Users

​Organizations

​Events

​Invitations

​Calllists

​Preset Teams

​Setlists

​Songs

​Positions

​Performance Folders

​Lead Requests

​Finance

​Payments

​Notifications

​Subscriptions

​Wrapped

​Response format

​Success response

​Error response

​Status codes

​Pagination

Base URL

Authentication

API Services

Users

Organizations

Events

Invitations

Calllists

Preset Teams

Setlists

Songs

Positions

Performance Folders

Lead Requests

Finance

Payments

Notifications

Subscriptions

Wrapped

Response format

Success response

Error response

Status codes

Pagination