Artist Endpoint Map

Related documentation: Artist Source of Truth Registry (canonical per-endpoint SoT + callers) · Artist Module Backend · Artist Product Vision · Frontend Artist · Artist Module Backend API

Purpose

This page explains:

• what each endpoint family is for
• where frontend should use it
• what user flow it belongs to
• which part of the system owns that flow

Use this page as the product/use-flow reference.

Use Artist Module Backend API for the exact runtime route inventory.

Use Artist Source of Truth Registry when you need which database owns each route, who calls it, and Promoters vs Artists vs Mongo boundaries.

How to read this page

Each section below is organized as:

• Endpoint
• What It Is For
• Frontend Use
• Typical Flow

This is the document frontend teams should use when deciding:

• where a route belongs in the UI
• what screen should call it
• what the expected user flow is

0. Agency provisioning (Phase 8)

Routes that let a fresh Auth/Core company bridge to an artists-company (the “agency”). Two flows: takeover (claim an existing unclaimed company) or creation (propose a brand-new one for admin approval). Backed by a new artists_provisioning_requests table (migration 20260525_market_provisioning_requests.sql) with strict business rules enforced via unique partial indexes:

• one pending request per Auth org globally
• one pending takeover per (target company, requester) pair
• existing artists_company_claims_approved_uniq keeps enforcing “one approved org per company”

On approve (single tx): the service writes a real artists_company_claims row (status=‘approved’) + flips companies.claimed=TRUE + closes the request. Creation also inserts the new companies row from the stored spec first. The existing claim-based ownership checks (IsCompanyOwnedByOrg, etc.) continue to work unchanged — no claim-consuming code needs to change.

No file upload anywhere (different from Backend-Kisum-Venues’ equivalent). Tenant submits only optional notes. Reviewer identity is stamped from JWT locals server-side; the FE never sends decisionBy* fields.

GET /api/v1/artists-companies/sleeping

What It Is For:

• search the central directory of unclaimed artists-companies that a tenant could claim
• search-required: returns [] when q.length < 2 (privacy + abuse vector — same comment as the Venues equivalent)
• joins hasPendingRequest + pendingRequestId per caller (scoped to the requesting Auth org only — no cross-org leak)

Query params: q, country, page, limit (default 25, max 200).

Frontend Use:

• SleepingCompanyBrowser on /settings/agency empty state

POST /api/v1/artists-companies/takeover-requests

What It Is For:

• submit a claim on an existing unclaimed agency
• body: { companyId, notes? } — companyId accepts either the bigint id or the uuid

Pre-checks before insert (friendly 409 messages):

• caller has no other pending provisioning request (any kind)
• caller has no other pending takeover on this specific target

Frontend Use:

• TakeoverRequestDialog after a user picks a row from the sleeping browser

POST /api/v1/artists-companies/creation-requests

What It Is For:

• propose a brand-new agency for admin approval
• body: { spec: { name, country, slug?, city?, roleType?, websiteUrl?, description?, contactEmail?, contactPhone? }, notes? }
• name + country required; spec is stored verbatim in JSONB until approve

Pre-checks: same single-pending-per-org guard as takeover.

Frontend Use:

• CreationRequestDialog on /settings/agency empty state

GET /api/v1/artists-companies/requests

What It Is For:

• the caller’s own provisioning history (unified list with kind discriminator, newest first)
• shows admin decisionNotes when present so the tenant sees rejection reasons

Query params: status (optional filter).

Frontend Use:

• MyAgencyRequestsList on /settings/agency empty state

GET /api/v1/me/agency

What It Is For:

• “what artists-company is my Auth org bridged to?” — returns the single approved claim’s company
• 404 = not bridged (canonical FE soft-gate signal; the tenant FE keys its banner + page two-mode render off this)

Frontend Use:

• useActiveAgency() hook in Frontend-Kisum-Artists — drives both the layout’s amber no-agency banner and the /settings/agency page’s two-mode render

Admin: GET|POST /internal/admin/artist-company-requests/*

Admin-only review queue (X-Internal-API-Key). 4 routes:

• GET /internal/admin/artist-company-requests?status=&kind=&requestedCompanyId=&page=&limit= — paginated queue
• GET /internal/admin/artist-company-requests/:requestId — single request detail
• POST /internal/admin/artist-company-requests/:requestId/approve — body { decisionByUserId, decisionByEmail, decisionByName, decisionNotes? }. Runs the takeover or creation side-effect (single tx). Idempotent on already-approved.
• POST /internal/admin/artist-company-requests/:requestId/reject — same body shape. Only valid from pending.

Frontend Use:

• proxied through Backend-Kisum-Admin → /api/v1/admin/artist-company-requests/* and consumed by Frontend-Kisum-Admin → System → Artist Company Requests

1. Directory and profiles

GET /api/v1/artists

What It Is For:

• list artists for search, tables, and selector UIs

Frontend Use:

• artist directory page
• artist picker modals
• shortlist add flow

Typical Flow:

1. user opens artist list
2. frontend loads artists
3. user filters/searches
4. user opens one artist detail

POST /api/v1/artists

What It Is For:

• create a new artist record

Frontend Use:

• artist creation form
• admin/operator data entry flow

Typical Flow:

1. user clicks create artist
2. frontend submits form
3. user lands on artist detail

GET /api/v1/artists/{id}

What It Is For:

• load artist summary/detail record

Frontend Use:

• artist detail header
• summary card
• page bootstrap

Typical Flow:

1. user opens artist detail
2. frontend loads main artist record
3. page tabs then load subresources

PATCH /api/v1/artists/{id}

What It Is For:

• update core artist fields

Frontend Use:

• edit artist form

Typical Flow:

1. user edits artist
2. frontend submits patch
3. refresh summary/header

DELETE /api/v1/artists/{id}

What It Is For:

• remove artist record where allowed

Frontend Use:

• destructive admin action only

Typical Flow:

1. user confirms delete
2. frontend calls delete
3. list view refreshes

GET|PUT /api/v1/artists/{id}/profile

What It Is For:

• read or update extended artist profile fields

Frontend Use:

• profile tab
• edit profile screen

Typical Flow:

1. open profile tab
2. load profile
3. edit and save profile

GET|PUT /api/v1/artists/{id}/genres

What It Is For:

• read or update artist genres

Frontend Use:

• taxonomy editor
• search tagging UI

GET|PUT /api/v1/artists/{id}/subgenres

What It Is For:

• read or update artist subgenres

Frontend Use:

• taxonomy editor
• recommendation/search refinement

GET|PUT /api/v1/artists/{id}/platform-accounts

What It Is For:

• manage artist platform handles and account links

Frontend Use:

• profile integrations tab

GET|PUT /api/v1/artists/{id}/provider-refs

What It Is For:

• manage provider/source references

Frontend Use:

• internal source-linking tools

GET|PUT /api/v1/artists/{id}/team

What It Is For:

• read or update artist-side team assignments

Response notes (GET):

• Each row includes person fields plus company fields: companyId, companyName, companyLogoUrl, companyRoleType, companySlug.
• When artist_team_assignments.company_id is unset, Artists resolves company from the person’s active company_people employment (prefers companies.role_type matching assignment_type, then is_primary).

Frontend Use:

• contacts/team tab

GET|PUT /api/v1/artists/{id}/roster

What It Is For:

• read or update artist roster relationships

Frontend Use:

• roster tab
• agency artist assignment flow

GET /api/v1/companies

What It Is For:

• list market companies / agencies / counterparties

Frontend Use:

• company directory
• agency picker
• claim flow lookup

POST /api/v1/companies

What It Is For:

• create company/agency directory records

Frontend Use:

• create agency/company flow

GET /api/v1/companies/{id}

What It Is For:

• load company detail

Frontend Use:

• agency/company detail page

PATCH /api/v1/companies/{id}

What It Is For:

• update company detail fields

Frontend Use:

• edit agency/company form

DELETE /api/v1/companies/{id}

What It Is For:

• delete company record where allowed

Frontend Use:

• admin destructive action

GET|PUT /api/v1/companies/{id}/people

What It Is For:

• read or maintain company contacts

Frontend Use:

• contacts tab

GET|PUT /api/v1/companies/{id}/locations

What It Is For:

• read or maintain company locations

Frontend Use:

• office/territory section

GET|PUT /api/v1/companies/{id}/genres

What It Is For:

• read or maintain company genre alignment

Frontend Use:

• company profile taxonomy

GET|PUT /api/v1/companies/{id}/roster

What It Is For:

• read or maintain roster associations for a company

Frontend Use:

• agency roster screen

GET|PUT /api/v1/companies/{id}/social-metrics

What It Is For:

• read or maintain company social/market metrics

Frontend Use:

• company profile analytics block

GET /api/v1/people

What It Is For:

• list people / contacts

Frontend Use:

• contacts list
• person picker

POST /api/v1/people

What It Is For:

• create a person/contact

Frontend Use:

• add contact flow

GET /api/v1/people/{id}

What It Is For:

• load one person/contact

Frontend Use:

• contact detail drawer/page

PATCH /api/v1/people/{id}

What It Is For:

• update contact record

Frontend Use:

• edit contact flow

DELETE /api/v1/people/{id}

What It Is For:

• delete contact record where allowed

Frontend Use:

• admin destructive action

GET /api/v1/people/{id}/companies

What It Is For:

• load the companies linked to a person

Frontend Use:

• contact affiliations section

GET|PUT /api/v1/people/{id}/platform-accounts

What It Is For:

• read or maintain platform accounts linked to a person

Frontend Use:

• contact external accounts/integrations

GET|POST|PATCH|DELETE /api/v1/genres, /subgenres, /regions, /countries, /states, /cities, /platforms, /provider-sources

What It Is For:

• maintain shared lookup/reference data

Frontend Use:

• dropdowns
• search/filtering
• data management screens

Typical Flow:

1. load page
2. fetch lookup data
3. populate selectors

2. Ownership and representation

POST /api/v1/market-companies/{id}/claims

What It Is For:

• submit a claim that an org owns or operates a company record

Frontend Use:

• “claim this company” action on company detail

Typical Flow:

1. user opens company
2. clicks claim
3. submits claim
4. UI shows pending review

GET /api/v1/market-companies/{id}/claims

What It Is For:

• list claim records on a company

Frontend Use:

• claim-history panel
• admin review list

POST /api/v1/market-companies/{id}/claims/{claimId}/approve

What It Is For:

• approve a company claim

Frontend Use:

• reviewer/admin approval action

POST /api/v1/market-companies/{id}/claims/{claimId}/reject

What It Is For:

• reject a company claim

Frontend Use:

• reviewer/admin rejection action

GET /api/v1/market-companies/{id}/ownership

What It Is For:

• load the current ownership/claim state

Frontend Use:

• company header badge
• claim status panel

POST /api/v1/artists/{id}/representation-claims

What It Is For:

• submit a claim that a company represents the artist

Frontend Use:

• add representation flow

Typical Flow:

1. open artist representation tab
2. submit claim
3. pending review / approval state

POST /api/v1/artists/{id}/representation-claims/{claimId}/approve

What It Is For:

• approve a representation claim

Frontend Use:

• reviewer action

POST /api/v1/artists/{id}/representation-claims/{claimId}/reject

What It Is For:

• reject a representation claim

Frontend Use:

• reviewer action

GET /api/v1/artists/{id}/representation

What It Is For:

• load the artist’s current representation state

Frontend Use:

• artist representation summary tab

POST /api/v1/artists/{id}/representation/disputes

What It Is For:

• open a dispute against a representation record

Frontend Use:

• dispute flow on representation tab

3. Availability and discovery

GET /api/v1/artists/{id}/availabilities

What It Is For:

• list artist availability entries

Frontend Use:

• availabilities tab
• artist calendar

POST /api/v1/artists/{id}/availabilities

What It Is For:

• create an availability entry

Frontend Use:

• create availability flow

PATCH /api/v1/artists/{id}/availabilities/{availabilityId}

What It Is For:

• update an availability entry

Frontend Use:

• edit availability flow

DELETE /api/v1/artists/{id}/availabilities/{availabilityId}

What It Is For:

• remove an availability entry

Frontend Use:

• delete availability action

GET /api/v1/marketplace/artist-availabilities

What It Is For:

• search published availabilities across artists

Frontend Use:

• marketplace search
• promoter discovery flow

Typical Flow:

1. promoter opens marketplace
2. filters by date/location
3. sees matching artists
4. opens profile or starts booking flow

4. Booking workflow

GET /api/v1/booking-requests

What It Is For:

• list booking requests

Frontend Use:

• requests inbox/list

POST /api/v1/booking-requests

What It Is For:

• create a booking request

Frontend Use:

• new inquiry / request form

Typical Flow:

1. user chooses artist
2. fills request
3. submits request
4. request appears in pipeline

GET /api/v1/booking-requests/{requestId}

What It Is For:

• load request detail

Frontend Use:

• request detail screen

PATCH /api/v1/booking-requests/{requestId}

What It Is For:

• update request detail

Frontend Use:

• edit draft/pending request

POST /api/v1/booking-requests/{requestId}/withdraw

What It Is For:

• withdraw a request

Frontend Use:

• request cancel/withdraw action

POST /api/v1/booking-requests/{requestId}/convert-to-offer

What It Is For:

• promote a request into an offer

Frontend Use:

• request-to-offer action in pipeline

GET /api/v1/booking-offers

What It Is For:

• list offers

Frontend Use:

• offer pipeline

POST /api/v1/booking-offers

What It Is For:

• create an offer directly

Frontend Use:

• direct offer creation

GET /api/v1/booking-offers/{offerId}

What It Is For:

• load offer detail

Frontend Use:

• offer detail screen

POST /api/v1/booking-offers/{offerId}/counter

What It Is For:

• counter an offer

Frontend Use:

• negotiation flow

POST /api/v1/booking-offers/{offerId}/accept

What It Is For:

• accept an offer

Frontend Use:

• deal acceptance action

POST /api/v1/booking-offers/{offerId}/decline

What It Is For:

• decline an offer

Frontend Use:

• decline action

POST /api/v1/booking-offers/{offerId}/cancel

What It Is For:

• cancel an offer

Frontend Use:

• offer cancellation

GET /api/v1/booking-offers/{offerId}/holds

What It Is For:

• list hold records on an offer

Frontend Use:

• holds section on offer detail

POST /api/v1/booking-offers/{offerId}/holds

What It Is For:

• create a hold

Frontend Use:

• add hold action

PATCH /api/v1/booking-offers/{offerId}/holds/{holdId}

What It Is For:

• update or release a hold

Frontend Use:

• hold state edit

GET /api/v1/bookings

What It Is For:

• list confirmed/current bookings

Frontend Use:

• bookings index

GET /api/v1/bookings/{bookingId}

What It Is For:

• load booking detail

Frontend Use:

• booking detail page shell

GET /api/v1/bookings/{bookingId}/activity

What It Is For:

• list booking activity timeline

Frontend Use:

• booking activity tab

POST /api/v1/bookings/{bookingId}/activity

What It Is For:

• append manual activity/note items

Frontend Use:

• add internal note / activity event

5. Contract workflow

GET /api/v1/market-companies/{id}/contract-templates

What It Is For:

• list contract templates for a company

Frontend Use:

• template library

POST /api/v1/market-companies/{id}/contract-templates

What It Is For:

• create a company contract template

Frontend Use:

• create template flow

GET /api/v1/contract-templates/{templateId}

What It Is For:

• load one template

Frontend Use:

• template detail

PATCH /api/v1/contract-templates/{templateId}

What It Is For:

• update template metadata

Frontend Use:

• edit template flow

POST /api/v1/contract-templates/{templateId}/activate

What It Is For:

• activate a template

Frontend Use:

• template status action

POST /api/v1/contract-templates/{templateId}/archive

What It Is For:

• archive a template

Frontend Use:

• template status action

POST /api/v1/contract-templates/{templateId}/upload-source

What It Is For:

• upload template source document

Frontend Use:

• template file upload

GET /api/v1/contract-templates/{templateId}/variables

What It Is For:

• list required/available variables for a template

Frontend Use:

• template variable mapping UI

GET /api/v1/bookings/{bookingId}/contracts

What It Is For:

• list contracts linked to a booking

Frontend Use:

• contracts tab inside booking detail

POST /api/v1/bookings/{bookingId}/contracts

What It Is For:

• create a booking-linked contract

Frontend Use:

• create contract from booking flow

Typical Flow:

1. open booking contracts tab
2. choose template
3. fill variables
4. create contract

GET /api/v1/contracts/{contractId}

What It Is For:

• load contract thread detail

Frontend Use:

• contract detail page

POST /api/v1/contracts/{contractId}/send

What It Is For:

• send contract for signing

Frontend Use:

• send action in contract detail

POST /api/v1/contracts/{contractId}/void

What It Is For:

• void a contract

Frontend Use:

• void action

GET /api/v1/contracts/{contractId}/versions

What It Is For:

• list versions for a contract

Frontend Use:

• version history tab

POST /api/v1/contracts/{contractId}/versions

What It Is For:

• create a new contract version

Frontend Use:

• revise contract flow

GET /api/v1/contracts/{contractId}/signatures

What It Is For:

• load signer and signature state

Frontend Use:

• signer progress panel

POST /api/v1/contracts/{contractId}/attachments

What It Is For:

• add contract attachments

Frontend Use:

• attachment upload

GET /api/v1/contracts/{contractId}/events

What It Is For:

• list contract audit events

Frontend Use:

• audit timeline tab

POST /api/v1/contracts/{contractId}/signers

What It Is For:

• add signer slots

Frontend Use:

• signer setup flow

PATCH /api/v1/contracts/{contractId}/signers/{signerId}

What It Is For:

• update signer configuration

Frontend Use:

• signer edit

POST /api/v1/contracts/{contractId}/signers/{signerId}/send

What It Is For:

• send a signer invite/action

Frontend Use:

• signer dispatch

POST /api/v1/contracts/{contractId}/signers/{signerId}/sign

What It Is For:

• complete signing action

Frontend Use:

• sign action

POST /api/v1/contracts/{contractId}/signers/{signerId}/decline

What It Is For:

• decline signing

Frontend Use:

• signer decline action

6. Touring and itinerary

GET /api/v1/artists/{id}/tour-plans

What It Is For:

• list tours for an artist

Frontend Use:

• tours index

POST /api/v1/artists/{id}/tour-plans

What It Is For:

• create a tour plan

Frontend Use:

• new tour flow

GET /api/v1/tour-plans/{tourPlanId}

What It Is For:

• load one tour plan

Frontend Use:

• tour detail screen

PATCH /api/v1/tour-plans/{tourPlanId}

What It Is For:

• update a tour plan

Frontend Use:

• edit tour flow

POST /api/v1/tour-plans/{tourPlanId}/stops

What It Is For:

• add a tour stop

Frontend Use:

• add stop action

PATCH /api/v1/tour-plans/{tourPlanId}/stops/{stopId}

What It Is For:

• update a stop

Frontend Use:

• stop edit flow

GET /api/v1/tour-plans/{tourPlanId}/routing

What It Is For:

• load route ordering and routing output

Frontend Use:

• routing tab

POST /api/v1/tour-plans/{tourPlanId}/routing/rebuild

What It Is For:

• rebuild route analysis

Frontend Use:

• recompute routing action

GET /api/v1/tour-plans/{tourPlanId}/conflicts

What It Is For:

• list routing or schedule conflicts

Frontend Use:

• conflict panel

GET /api/v1/bookings/{bookingId}/logistics

What It Is For:

• load booking logistics summary

Frontend Use:

• logistics tab

POST /api/v1/bookings/{bookingId}/logistics

What It Is For:

• create logistics record if missing

Frontend Use:

• initial logistics setup

PATCH /api/v1/bookings/{bookingId}/logistics

What It Is For:

• update logistics record

Frontend Use:

• logistics editing

GET /api/v1/bookings/{bookingId}/itinerary

What It Is For:

• load itinerary items for a booking

Frontend Use:

• itinerary tab

POST /api/v1/bookings/{bookingId}/itinerary-items

What It Is For:

• create itinerary item

Frontend Use:

• add itinerary entry

PATCH /api/v1/bookings/{bookingId}/itinerary-items/{itemId}

What It Is For:

• update itinerary item

Frontend Use:

• edit itinerary entry

7. Logistics submissions and approvals

GET /api/v1/bookings/{bookingId}/logistics-submissions

What It Is For:

• list logistics submissions for a booking

Frontend Use:

• logistics approvals tab

POST /api/v1/bookings/{bookingId}/logistics-submissions

What It Is For:

• create a draft logistics submission

Frontend Use:

• promoter coordinator creates hotel / hospitality / technical / transport proposal

Typical Flow:

1. open booking logistics approvals
2. create submission
3. save draft
4. submit for artist-side review

GET /api/v1/logistics-submissions/{submissionId}

What It Is For:

• load one submission

Frontend Use:

• submission detail / review screen

PATCH /api/v1/logistics-submissions/{submissionId}

What It Is For:

• edit draft or editable submission fields

Frontend Use:

• update proposal

POST /api/v1/logistics-submissions/{submissionId}/submit

What It Is For:

• send a draft proposal into review

Frontend Use:

• submit action for promoter-side coordinator

POST /api/v1/logistics-submissions/{submissionId}/approve

What It Is For:

• approve a proposal

Frontend Use:

• artist-side approval action

POST /api/v1/logistics-submissions/{submissionId}/reject

What It Is For:

• reject a proposal

Frontend Use:

• artist-side rejection action

POST /api/v1/logistics-submissions/{submissionId}/request-changes

What It Is For:

• send a submission back with requested changes

Frontend Use:

• artist-side review action

GET /api/v1/logistics-submissions/{submissionId}/decisions

What It Is For:

• load the decision history for one submission

Frontend Use:

• review/audit panel

8. Relationship memory and trust

GET /api/v1/relationships

What It Is For:

• list relationships

Frontend Use:

• relationship search/list

GET /api/v1/relationships/{relationshipId}

What It Is For:

• load relationship summary

Frontend Use:

• relationship detail

GET|POST /api/v1/relationships/{relationshipId}/notes

What It Is For:

• read or add org-private relationship notes

Frontend Use:

• internal notes tab

GET|POST /api/v1/relationships/{relationshipId}/flags

What It Is For:

• read or add org-private flags

Frontend Use:

• risk/flag section

GET|POST /api/v1/relationships/{relationshipId}/ratings

What It Is For:

• read or add org-private manual ratings

Frontend Use:

• trust input section

GET /api/v1/relationships/{relationshipId}/trust-score

What It Is For:

• load normalized trust output

Frontend Use:

• trust badge / trust panel

GET /api/v1/relationships/{relationshipId}/signals

What It Is For:

• load signal breakdown behind trust

Frontend Use:

• trust explanation panel

GET /api/v1/artists/{id}/booking-history

What It Is For:

• load artist booking history

Frontend Use:

• history tab on artist detail

GET /api/v1/promoters/{id}/booking-history

What It Is For:

• load promoter booking history

Frontend Use:

• promoter relationship analysis

GET /api/v1/agencies/{id}/booking-history

What It Is For:

• load agency booking history

Frontend Use:

• agency relationship analysis

9. Finance visibility

GET /api/v1/bookings/{bookingId}/finance-status

What It Is For:

• show overall finance visibility for a booking

Frontend Use:

• finance panel inside booking detail

GET /api/v1/bookings/{bookingId}/payment-schedule

What It Is For:

• show payment schedule visibility

Frontend Use:

• payment schedule tab/panel

GET /api/v1/bookings/{bookingId}/deposit-status

What It Is For:

• show deposit visibility

Frontend Use:

• deposit badge / summary

POST /api/v1/bookings/{bookingId}/finance-handoff

What It Is For:

• record that booking workflow has been handed off to Finance

Frontend Use:

• handoff action

10. Dashboards and shortlists

GET /api/v1/agencies/{id}/dashboard

What It Is For:

• load agency dashboard summary

Frontend Use:

• agency home/dashboard

GET /api/v1/agencies/{id}/roster/pipeline

What It Is For:

• load agency roster pipeline

Frontend Use:

• agency pipeline screen

GET /api/v1/agencies/{id}/tasks

What It Is For:

• load agency tasks

Frontend Use:

• task widgets / task list

GET /api/v1/agencies/{id}/activity

What It Is For:

• load agency activity stream

Frontend Use:

• dashboard activity feed

GET /api/v1/promoters/{id}/dashboard

What It Is For:

• load promoter dashboard summary from the artist-network side

Frontend Use:

• promoter-facing artist-market dashboard

GET /api/v1/promoters/{id}/shortlists

What It Is For:

• load promoter shortlists

Frontend Use:

• shortlist page

POST /api/v1/promoters/{id}/shortlists

What It Is For:

• create shortlist

Frontend Use:

• create shortlist action

POST /api/v1/promoters/{id}/shortlists/{shortlistId}/artists

What It Is For:

• add artist to shortlist

Frontend Use:

• shortlist add flow from artist marketplace/list

GET /api/v1/promoters/{id}/inquiries

What It Is For:

• load promoter inquiries/read model

Frontend Use:

• inquiry pipeline screen

GET /api/v1/promoters/{id}/offers

What It Is For:

• load promoter offers/read model

Frontend Use:

• offers pipeline screen

11. Marketplace search and research

GET /api/v1/marketplace/artists

What It Is For:

• search artists in marketplace context

Frontend Use:

• artist marketplace list

GET /api/v1/marketplace/agencies

What It Is For:

• search agencies

Response (per row, Postgres companies):

• roster_artists_count / roster_size (JSON) — companies.roster_size, maintained by Postgres trigger from company_rosters (migration 20260529_restore_companies_roster_size.sql). Fast list reads; always updated when roster rows change.
• relationship_count — not roster size; count of artists_relationships graph edges (often 0 for browse)

Source of truth: company_rosters. Cache: companies.roster_size. Run scripts/apply-roster-size-cache.sh once per environment.

After bulk TRUNCATE on company_rosters, run SELECT refresh_all_companies_roster_size(); as a privileged DB user.

Query params (sort/filter):

• q — name/slug search
• sort or sortBy — rosterArtistsCount (default), rosterSize, effectiveRoster, name, claimed, relationshipCount
• order or sortType — asc | desc (default desc for roster)
• page, limit

Default list order: rosterArtistsCount DESC (largest agency rosters first), then name ASC.

Frontend Use:

• agency marketplace/research list

GET /api/v1/marketplace/promoters

What It Is For:

• search promoters

Frontend Use:

• promoter research list

GET /api/v1/marketplace/talent-buyers

What It Is For:

• search talent buyers

Frontend Use:

• buyer research list

GET /api/v1/marketplace/venues

What It Is For:

• search venues for artist-side research

Frontend Use:

• venue research list