Backend Base API Specification

Version: 1.0.0
Audience: backend developers, frontend developers, QA, integrators
Status: API specification

1. Purpose of this document

This document is the Base Backend API catalog.

It focuses on:

route groups
request headers
common request/response expectations
endpoint families
deprecation visibility for old groups

It intentionally avoids long architectural explanations.
For architecture and access rules, see:

KISUM_BASE_ARCHITECTURE.md

For integration examples, see:

KISUM_BASE_INTEGRATION.md

2. Base URLs

https://api-v2.kisum.dev/api — Staging
http://localhost:3099/api — Local

3. Required headers for protected routes

Authorization: Bearer <JWT_FROM_AUTH_SERVICE>
x-org: <COMPANY_ID>
Content-Type: application/json

Notes

Authorization must contain a JWT issued by Auth Backend
x-org must contain the active company context
tenant-scoped routes must reject missing or malformed x-org

4. Common content types

application/json for most requests
multipart/form-data for uploads and attachments
application/xml may appear in legacy Swagger definitions, but JSON is the primary format

5. Common response codes

200 / 201 / default — success
400 — invalid request / missing malformed x-org
401 — missing or invalid JWT
403 — authenticated but not allowed
500 — internal server error
503 — effective access cannot be resolved from Auth

6. Active route groups

These are the active business-domain groups in Base Backend.

Agencies — 14 operations
Agreements — 10 operations
Ai — 6 operations
Analytics — 1 operation
Approval — 6 operations
Artists — 27 operations
Avails — 9 operations
Cash Flow — 1 operation
Countries — 9 operations
Companies — 11 operations (business metadata only — not membership/access)
Dashboard — 3 operations
Events — 26 operations
Event Expense — 17 operations (estimated only; actual expenses blocked)
Event Expense - Approval — 7 operations (source of truth for actual expenses in this service scope)
Event Group — 10 operations
Event Income — 14 operations
Event Tax — 6 operations
Event Ticket — 18 operations
Event Intelligence Copilot — 3 operations
Kisum — 7 operations (legacy /kisum/* aliases)
Integrations - Finance — 11 operations
Exchange — 2 operations
Festivals — 6 operations
Files — 1 operation
Genres — 1 operation
Integrations — 2 operations
News — 1 operation
Nextcloud — 3 operations
Notifications — 6 operations
Offer — 16 operations
Rankings — 5 operations
Reviews — 1 operation
Roster — 6 operations
Regions — 3 operations
Setlistfm — 8 operations
Tasks — 8 operations
Transactions — 2 operations
Trend — 1 operation
Vendors — 11 operations
Vendors System — 15 operations
Venues — 19 operations
Xero — 11 operations
Untagged — 2 operations (BLOCKER — must be categorized before production release)

7. Deprecated legacy groups

These groups must not be used in Base Backend anymore.

Auth — ❌ deprecated; moved to Auth Backend
Company Users — ❌ deprecated; moved to Auth Backend
Company User Invitations — ❌ deprecated; moved to Auth Backend
Company Teams — ❌ deprecated; moved to Auth Backend
Packages — ❌ deprecated; moved to Platform Core Backend
Permissions — ❌ deprecated; moved to Auth Backend
Role — ❌ deprecated; moved to Auth Backend
Subscription — ❌ deprecated; moved to Platform Core Backend
Users — ❌ deprecated; moved to Auth Backend

8. Table of contents

Active sections

Agencies
Agreements
Ai
Analytics
Approval
Artists
Avails
Cash Flow
Countries
Companies
Dashboard
Events
Event Expense
Event Expense - Approval
Event Group
Event Income
Event Tax
Event Ticket
Event Intelligence Copilot
Kisum
Integrations - Finance
Exchange
Festivals
Files
Genres
Integrations
News
Nextcloud
Notifications
Offer
Rankings
Reviews
Roster
Regions
Setlistfm
Tasks
Transactions
Trend
Vendors
Vendors System
Venues
Xero
Untagged

9. Endpoint family summary

This section is intentionally high-level.
For junior developers, the goal is to understand what kind of routes live in each group.

Agencies

Typical responsibilities:

list agencies
create agency
update agency
delete agency
manage agency roster
manage agency team members

Typical routes:

GET /agencies
POST /agencies
GET /agencies/search
GET /agencies/{id}
PUT /agencies/{id}
DELETE /agencies/{id}
GET /agencies/{id}/roster
POST /agencies/{id}/roster
DELETE /agencies/{id}/roster/{rosterId}
GET /agencies/{id}/team
POST /agencies/{id}/team
PUT /agencies/{id}/team/{teamId}
DELETE /agencies/{id}/team/{teamId}

Agreements

Typical responsibilities:

retrieve agreements
create agreement assets
generate or delete agreement PDFs

Typical routes:

GET /agreements
GET /agreements/{id}
PUT /agreements/{id}
GET /agreements/{id}/{assets}
POST /agreements/{id}/{assets}
PUT /agreements/{id}/{assets}
GET /agreements/{id}/{assets}/{extra}
POST /agreements/create
POST /agreements/create/pdf/{offerId}
DELETE /agreements/delete/pdf/{offerId}

Ai

Typical responsibilities:

AI assistant
Gemini route
AI conversation/chat routes

Typical routes:

POST /ai-kisum/gemini
POST /ai-kisum
POST /ai-kisum/n8n
GET /ai-kisum/conversation/{id}
POST /ai-kisum/conversation
POST /ai-kisum/chat

Analytics

Typical responsibilities:

analytics views exposed by Base

Typical routes:

GET /analytics/financials

Approval

Typical responsibilities:

approval queue
approve/reject/cancel actions
approval views by user

Typical routes:

GET /approval
GET /approval/by-user
POST /approval/{id}/approve
POST /approval/{id}/reject
POST /approval/{id}/cancel
GET /approval/{id}

Artists

Typical responsibilities:

artist CRUD
discovery/search
stats
demographics
prediction
historical data
platforms
events
contacts
bios

Typical route families:

GET /artists
POST /artists
GET /artists/search
GET /artists/{id}
GET /artists/{id}/stats
GET /artists/{id}/demographics
GET /artists/{id}/events
POST /artists/{id}/bio
POST /artists/{id}/prediction-v2
POST /artists/{id}/prediction-v3

Avails

Typical responsibilities:

avails list
avails by user
avails-linked shows

Typical route families:

GET /avails
POST /avails
GET /avails/user
GET /avails/{id}/shows
GET /avails/{id}/shows-summary

Additional active groups

The same pattern continues for:

Cash Flow
Countries
Companies
Dashboard
Events
Event Expense
Event Expense - Approval
Event Group
Event Income
Event Tax
Event Ticket
Event Intelligence Copilot
Kisum
Integrations - Finance
Exchange
Festivals
Files
Genres
Integrations
News
Nextcloud
Notifications
Offer
Rankings
Reviews
Roster
Regions
Setlistfm
Tasks
Transactions
Trend
Vendors
Vendors System
Venues
Xero

Each of those route groups remains active in Base unless explicitly marked deprecated.

10. Request examples

Generic GET example

curl -X GET 'http://localhost:3099/api/events?type=all&page=1&limit=20'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'

Generic POST example

curl -X POST 'http://localhost:3099/api/artists/{id}/bio'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'   -H 'Content-Type: application/json'   -d '{
    "resJson": {}
  }'

Generic upload example

curl -X POST 'http://localhost:3099/api/files/upload'   -H 'Authorization: Bearer <JWT>'   -H 'x-org: <COMPANY_ID>'   -F 'file=@example.pdf'