Artist Module Backend API

Related documentation: Artist Source of Truth Registry · Artist Module Backend · Artist Product Vision · Artist Endpoint Map · Frontend Artist · Error Contract

Purpose

This page is the runtime-oriented route inventory for the Artist module backend.

Use this page for:

• exact route families that currently exist
• auth/header rules
• ID behavior
• route discovery by capability area

Use Artist Endpoint Map when the question is:

• what is this endpoint for
• what screen should call it
• what flow does it belong to

Runtime basics

• runtime: Go / Fiber
• base path: /api/v1
• health route: GET /health
• docs artifact: generated OpenAPI from backend repo

Auth model

All /api/v1/* routes accept either:

Bearer mode

Required headers:

• Authorization: Bearer <JWT>
• x-org: <core-company-id>

Internal mode

Required header:

• X-Internal-API-Key: <MARKET_INTERNAL_API_KEY>

Response pattern

Success:

{
  "success": true,
  "data": {}
}

Error:

{
  "success": false,
  "error": {
    "code": "SOME_CODE",
    "message": "Readable explanation"
  }
}

ID rules

The service still uses mixed ID families.

Typical rule:

• main directory entities often expose UUID path IDs
• geo and some compatibility entities still expose integer path IDs

Frontend should not guess. It should follow the generated OpenAPI and the actual returned IDs.

Include and subresource model

Main entity reads are intentionally light by default.

Use:

• include=... for moderate detail expansion
• dedicated subresource routes for tabs and independently loaded sections

Typical examples:

• GET /api/v1/artists?include=profile,genres
• GET /api/v1/companies/{id}?include=people,locations

Route inventory

Directory and reference routes

Artists

• GET /api/v1/artists
• POST /api/v1/artists
• GET /api/v1/artists/{id}
• PATCH /api/v1/artists/{id}
• DELETE /api/v1/artists/{id}
• GET /api/v1/artists/{id}/profile
• PUT /api/v1/artists/{id}/profile
• GET /api/v1/artists/{id}/genres
• PUT /api/v1/artists/{id}/genres
• GET /api/v1/artists/{id}/subgenres
• PUT /api/v1/artists/{id}/subgenres
• GET /api/v1/artists/{id}/platform-accounts
• PUT /api/v1/artists/{id}/platform-accounts
• GET /api/v1/artists/{id}/provider-refs
• PUT /api/v1/artists/{id}/provider-refs
• GET /api/v1/artists/{id}/team
• PUT /api/v1/artists/{id}/team
• GET /api/v1/artists/{id}/roster
• PUT /api/v1/artists/{id}/roster

Companies

• GET /api/v1/companies
• POST /api/v1/companies
• GET /api/v1/companies/{id}
• PATCH /api/v1/companies/{id}
• DELETE /api/v1/companies/{id}
• GET /api/v1/companies/{id}/people
• PUT /api/v1/companies/{id}/people
• GET /api/v1/companies/{id}/locations
• PUT /api/v1/companies/{id}/locations
• GET /api/v1/companies/{id}/genres
• PUT /api/v1/companies/{id}/genres
• GET /api/v1/companies/{id}/roster
• PUT /api/v1/companies/{id}/roster
• GET /api/v1/companies/{id}/social-metrics
• PUT /api/v1/companies/{id}/social-metrics

People

• GET /api/v1/people
• POST /api/v1/people
• GET /api/v1/people/{id}
• PATCH /api/v1/people/{id}
• DELETE /api/v1/people/{id}
• GET /api/v1/people/{id}/companies
• GET /api/v1/people/{id}/platform-accounts
• PUT /api/v1/people/{id}/platform-accounts

Taxonomy, geo, platform, provider

• GET /api/v1/genres
• POST /api/v1/genres
• GET /api/v1/genres/{id}
• PATCH /api/v1/genres/{id}
• DELETE /api/v1/genres/{id}
• GET /api/v1/subgenres
• POST /api/v1/subgenres
• GET /api/v1/subgenres/{id}
• PATCH /api/v1/subgenres/{id}
• DELETE /api/v1/subgenres/{id}
• GET /api/v1/regions
• POST /api/v1/regions
• GET /api/v1/regions/{id}
• PATCH /api/v1/regions/{id}
• DELETE /api/v1/regions/{id}
• GET /api/v1/regions/{id}/subregions
• GET /api/v1/regions/{id}/countries
• GET /api/v1/subregions/{id}/countries
• GET /api/v1/countries
• POST /api/v1/countries
• GET /api/v1/countries/{id}
• PATCH /api/v1/countries/{id}
• DELETE /api/v1/countries/{id}
• GET /api/v1/countries/{id}/states
• GET /api/v1/countries/{id}/cities
• GET /api/v1/states
• POST /api/v1/states
• GET /api/v1/states/{id}
• PATCH /api/v1/states/{id}
• DELETE /api/v1/states/{id}
• GET /api/v1/states/{id}/cities
• GET /api/v1/cities
• POST /api/v1/cities
• GET /api/v1/cities/{id}
• PATCH /api/v1/cities/{id}
• DELETE /api/v1/cities/{id}
• GET /api/v1/platforms
• POST /api/v1/platforms
• GET /api/v1/platforms/{id}
• PATCH /api/v1/platforms/{id}
• DELETE /api/v1/platforms/{id}
• GET /api/v1/provider-sources
• POST /api/v1/provider-sources
• GET /api/v1/provider-sources/{id}
• PATCH /api/v1/provider-sources/{id}
• DELETE /api/v1/provider-sources/{id}

Ownership, representation, and availability

• POST /api/v1/market-companies/{id}/claims
• GET /api/v1/market-companies/{id}/claims
• POST /api/v1/market-companies/{id}/claims/{claimId}/approve
• POST /api/v1/market-companies/{id}/claims/{claimId}/reject
• GET /api/v1/market-companies/{id}/ownership
• POST /api/v1/artists/{id}/representation-claims
• POST /api/v1/artists/{id}/representation-claims/{claimId}/approve
• POST /api/v1/artists/{id}/representation-claims/{claimId}/reject
• GET /api/v1/artists/{id}/representation
• POST /api/v1/artists/{id}/representation/disputes
• GET /api/v1/artists/{id}/availabilities
• POST /api/v1/artists/{id}/availabilities
• PATCH /api/v1/artists/{id}/availabilities/{availabilityId}
• DELETE /api/v1/artists/{id}/availabilities/{availabilityId}
• GET /api/v1/marketplace/artist-availabilities

Booking workflow

• GET /api/v1/booking-requests
• POST /api/v1/booking-requests
• GET /api/v1/booking-requests/{requestId}
• PATCH /api/v1/booking-requests/{requestId}
• POST /api/v1/booking-requests/{requestId}/withdraw
• POST /api/v1/booking-requests/{requestId}/convert-to-offer
• GET /api/v1/booking-offers
• POST /api/v1/booking-offers
• GET /api/v1/booking-offers/{offerId}
• POST /api/v1/booking-offers/{offerId}/counter
• POST /api/v1/booking-offers/{offerId}/accept
• POST /api/v1/booking-offers/{offerId}/decline
• POST /api/v1/booking-offers/{offerId}/cancel
• GET /api/v1/booking-offers/{offerId}/holds
• POST /api/v1/booking-offers/{offerId}/holds
• PATCH /api/v1/booking-offers/{offerId}/holds/{holdId}
• GET /api/v1/bookings
• GET /api/v1/bookings/{bookingId}
• GET /api/v1/bookings/{bookingId}/activity
• POST /api/v1/bookings/{bookingId}/activity

Contracts

• GET /api/v1/market-companies/{id}/contract-templates
• POST /api/v1/market-companies/{id}/contract-templates
• GET /api/v1/contract-templates/{templateId}
• PATCH /api/v1/contract-templates/{templateId}
• POST /api/v1/contract-templates/{templateId}/activate
• POST /api/v1/contract-templates/{templateId}/archive
• POST /api/v1/contract-templates/{templateId}/upload-source
• GET /api/v1/contract-templates/{templateId}/variables
• GET /api/v1/bookings/{bookingId}/contracts
• POST /api/v1/bookings/{bookingId}/contracts
• GET /api/v1/contracts/{contractId}
• POST /api/v1/contracts/{contractId}/send
• POST /api/v1/contracts/{contractId}/void
• GET /api/v1/contracts/{contractId}/versions
• POST /api/v1/contracts/{contractId}/versions
• GET /api/v1/contracts/{contractId}/signatures
• POST /api/v1/contracts/{contractId}/attachments
• GET /api/v1/contracts/{contractId}/events
• POST /api/v1/contracts/{contractId}/signers
• PATCH /api/v1/contracts/{contractId}/signers/{signerId}
• POST /api/v1/contracts/{contractId}/signers/{signerId}/send
• POST /api/v1/contracts/{contractId}/signers/{signerId}/sign
• POST /api/v1/contracts/{contractId}/signers/{signerId}/decline

Touring, itinerary, and logistics

• GET /api/v1/artists/{id}/tour-plans
• POST /api/v1/artists/{id}/tour-plans
• GET /api/v1/tour-plans/{tourPlanId}
• PATCH /api/v1/tour-plans/{tourPlanId}
• POST /api/v1/tour-plans/{tourPlanId}/stops
• PATCH /api/v1/tour-plans/{tourPlanId}/stops/{stopId}
• GET /api/v1/tour-plans/{tourPlanId}/routing
• POST /api/v1/tour-plans/{tourPlanId}/routing/rebuild
• GET /api/v1/tour-plans/{tourPlanId}/conflicts
• GET /api/v1/bookings/{bookingId}/logistics
• POST /api/v1/bookings/{bookingId}/logistics
• PATCH /api/v1/bookings/{bookingId}/logistics
• GET /api/v1/bookings/{bookingId}/itinerary
• POST /api/v1/bookings/{bookingId}/itinerary-items
• PATCH /api/v1/bookings/{bookingId}/itinerary-items/{itemId}
• GET /api/v1/bookings/{bookingId}/logistics-submissions
• POST /api/v1/bookings/{bookingId}/logistics-submissions
• GET /api/v1/logistics-submissions/{submissionId}
• PATCH /api/v1/logistics-submissions/{submissionId}
• POST /api/v1/logistics-submissions/{submissionId}/submit
• POST /api/v1/logistics-submissions/{submissionId}/approve
• POST /api/v1/logistics-submissions/{submissionId}/reject
• POST /api/v1/logistics-submissions/{submissionId}/request-changes
• GET /api/v1/logistics-submissions/{submissionId}/decisions

Relationship intelligence and read models

• GET /api/v1/relationships
• GET /api/v1/relationships/{relationshipId}
• GET /api/v1/relationships/{relationshipId}/notes
• POST /api/v1/relationships/{relationshipId}/notes
• GET /api/v1/relationships/{relationshipId}/flags
• POST /api/v1/relationships/{relationshipId}/flags
• GET /api/v1/relationships/{relationshipId}/ratings
• POST /api/v1/relationships/{relationshipId}/ratings
• GET /api/v1/relationships/{relationshipId}/trust-score
• GET /api/v1/relationships/{relationshipId}/signals
• GET /api/v1/artists/{id}/booking-history
• GET /api/v1/promoters/{id}/booking-history
• GET /api/v1/agencies/{id}/booking-history
• GET /api/v1/bookings/{bookingId}/finance-status
• GET /api/v1/bookings/{bookingId}/payment-schedule
• GET /api/v1/bookings/{bookingId}/deposit-status
• POST /api/v1/bookings/{bookingId}/finance-handoff
• GET /api/v1/agencies/{id}/dashboard
• GET /api/v1/agencies/{id}/roster/pipeline
• GET /api/v1/agencies/{id}/tasks
• GET /api/v1/agencies/{id}/activity
• GET /api/v1/promoters/{id}/dashboard
• GET /api/v1/promoters/{id}/shortlists
• POST /api/v1/promoters/{id}/shortlists
• POST /api/v1/promoters/{id}/shortlists/{shortlistId}/artists
• GET /api/v1/promoters/{id}/inquiries
• GET /api/v1/promoters/{id}/offers
• GET /api/v1/marketplace/artists
• GET /api/v1/marketplace/agencies
• GET /api/v1/marketplace/promoters
• GET /api/v1/marketplace/talent-buyers
• GET /api/v1/marketplace/venues

Public route

Outside the auth-protected /api/v1 surface:

• GET /health

Practical documentation rule

Use:

• this page for the exact route surface
• Artist Endpoint Map for route purpose, frontend screen mapping, and flow explanations