Partner API v1.0

Bandshare API

REST API for accessing Artist Lab artist profiles, float status, and trust score data. Designed for the Bandshare platform integration.

Base URL: https://api.musicata.io/api/v1/bandshare

1. Overview

The Bandshare API provides read-only access to Artist Lab artist data for authorised partner integrations. It serves as the pre-Mozart bridge, allowing Bandshare to poll artist profiles and trust scores until the full event layer is operational.

Every artist on Artist Lab has a unique Artist Number (format: MUS-XXXXXX) that serves as the primary lookup key across all endpoints.

REST

JSON over HTTPS

v1.0

Versioned from day one

1000/hr

Default rate limit

2. Authentication

All authenticated endpoints require an API key passed in the Authorization header:

Authorization: Bearer sk_bsr_your_secret_key_here

API keys are issued by the Artist Lab admin team. Each key has:

Scopes - Controls which endpoints the key can access (artist:read, trust:read)
Rate limit - Per-key hourly request limit (default 1000)
Expiry - Optional expiration date
IP allowlist - Optional CIDR-based IP restriction

Important: Your API key is shown exactly once when generated. Store it securely. If lost, the key must be revoked and a new one issued.

3. Endpoints

GET /health

Public health check. No authentication required.

curl https://api.musicata.io/api/v1/bandshare/health

Response 200

{
  "status": "ok",
  "version": "1.0",
  "timestamp": "2026-02-19T12:00:00.000Z"
}

GET /artists/:artistNumber

Retrieve a single artist profile with float status and trust score data.

Scope: artist:read

curl https://api.musicata.io/api/v1/bandshare/artists/MUS-100001 \
  -H "Authorization: Bearer sk_bsr_your_key"

Response 200

{
  "success": true,
  "request_id": "req_01JP4X5K8M3N2Q7",
  "data": {
    "artist_number": "MUS-100001",
    "name": "Crimson Medici",
    "tier": "power",
    "member_since": "2025-12-01T00:00:00.000Z",
    "float_status": "ready_to_float",
    "float_eligible_at": "2025-12-31T00:00:00.000Z",
    "trust_score": {
      "score": 9065,
      "tokens_to_issue": 9065,
      "min_token_price_usd": 10,
      "potential_raise_usd": 90650,
      "algorithm_version": "1.0",
      "calculated_at": "2026-02-19T01:00:00.000Z",
      "score_date": "2026-02-19",
      "is_locked": false,
      "data_integrity_passed": true
    }
  }
}

The trust_score object is null until the artist reaches ready_to_float status. The score equals tokens_to_issue (1:1 ratio) and is uncapped. See Trust Score Gating.

GET /artists

List all artists enrolled in Bandshare.

Scope: artist:read

Parameter	Type	Default	Description
`cursor`	string	-	Artist number of last seen record (preferred pagination)
`limit`	integer	50	Results per page (max 100)
`page`	integer	1	Offset fallback; ignored when cursor is provided
`status`	string	-	Filter by float status (pipe-separated, e.g. `ready_to_float\|floated`)
`updated_since`	ISO 8601	-	Delta sync: only artists updated after this timestamp
`sort`	string	`member_since`	Sort field: `member_since`, `float_eligible_at`, `name`
`order`	string	`desc`	`asc` or `desc`

curl "https://api.musicata.io/api/v1/bandshare/artists?status=ready_to_float&limit=10" \
  -H "Authorization: Bearer sk_bsr_your_key"

Response 200

{
  "success": true,
  "request_id": "req_01JP4X5K8M3N2Q8",
  "data": [
    {
      "artist_number": "MUS-100001",
      "name": "Crimson Medici",
      "float_status": "ready_to_float",
      "member_since": "2025-12-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 10,
    "has_next": true,
    "next_cursor": "MUS-100010"
  }
}

POST /artists/lookup

Bulk lookup by artist number. Max 100 per request.

Scope: artist:read

curl -X POST https://api.musicata.io/api/v1/bandshare/artists/lookup \
  -H "Authorization: Bearer sk_bsr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"artist_numbers": ["MUS-100001", "MUS-100002", "MUS-100042"]}'

Response 200

{
  "success": true,
  "request_id": "req_01JP4X5K8M3N2Q9",
  "data": {
    "MUS-100001": {
      "artist_number": "MUS-100001",
      "name": "Crimson Medici",
      "float_status": "pre_ipo",
      "trust_score": null
    },
    "MUS-100002": {
      "artist_number": "MUS-100002",
      "name": "Twayn",
      "float_status": "incubation",
      "trust_score": null
    }
  },
  "not_found": [
    "MUS-100042"
  ],
  "requested": 3,
  "found": 2
}

GET /artists/:artistNumber/trust-history

Historical trust scores for a float-eligible artist.

Scope: trust:read

Parameter	Type	Default	Description
`from`	YYYY-MM-DD	30 days ago	Inclusive start date
`to`	YYYY-MM-DD	today	Inclusive end date
`limit`	integer	90	Max results (max 365)

curl "https://api.musicata.io/api/v1/bandshare/artists/MUS-100001/trust-history?from=2026-01-01&to=2026-02-19" \
  -H "Authorization: Bearer sk_bsr_your_key"

Response 200

{
  "success": true,
  "request_id": "req_01JP4X5K8M3N2QA",
  "data": [
    {
      "score_date": "2026-02-19",
      "score": 9065,
      "tokens_to_issue": 9065,
      "algorithm_version": "1.0",
      "calculated_at": "2026-02-19T01:00:00.000Z",
      "is_locked": false,
      "data_integrity_passed": true
    }
  ],
  "period": {
    "from": "2026-01-01",
    "to": "2026-02-19"
  },
  "artist_number": "MUS-100001"
}

Returns 404 if the artist is not in a float-eligible state (ready_to_float, ipo_in_progress, or floated).

GET /usage

Check your current rate limit status.

Scope: any

curl https://api.musicata.io/api/v1/bandshare/usage \
  -H "Authorization: Bearer sk_bsr_your_key"

Response 200

{
  "success": true,
  "request_id": "req_01JP4X5K8M3N2QB",
  "data": {
    "period": "hourly",
    "limit": 1000,
    "used": 153,
    "remaining": 847,
    "resets_at": "2026-02-19T13:00:00.000Z",
    "total_requests_lifetime": 48291
  }
}

4. Float Status

Every opted-in artist has a float_status that reflects their journey from signup to token float:

Status	Meaning
`incubation`	Signed up less than 30 days ago. Data is being collected and verified.
`pre_ipo`	Past 30-day mark, trust score not yet calculated or not public.
`pending_integrity`	Data integrity issue detected. Under review.
`ready_to_float`	All checks passed. Trust score available. Artist can initiate float.
`ipo_in_progress`	Float initiated. Trust score is locked.
`floated`	Float complete. Tokens minted and trading.

Statuses progress roughly in order, but an artist can move to pending_integrity from any state if an issue is detected.

5. Trust Score Gating

Trust score data is not freely available. The trust_score field is only populated when all of these conditions are met:

Artist has opted in to Bandshare
Data integrity status is clean
Account is at least 30 days old
A trust score has been calculated and marked public

Until these conditions are met, trust_score returns null. The float_status field tells you why:

incubation = too new (condition 3)
pre_ipo = no trust score yet (condition 4)
pending_integrity = integrity issue (condition 2)

Sanitisation: Trust scores are deliberately simplified for the API. Internal fields like scoring components, quality multipliers, and fraud flag details are never exposed. Only the final score, token count, pricing, algorithm version, calculation timestamp, lock status, and a boolean integrity check are returned.

6. Rate Limits

Rate limits are enforced per API key on a fixed hourly window. Every response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1708372800
X-RateLimit-Window: 3600

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds until the window resets.

Limit	Value
Default per key	1,000 requests/hour
Hard ceiling	5,000 requests/hour (cannot be exceeded)
Bulk lookup body	100 artist numbers per request
Trust history range	365 days maximum

Need a higher limit? Contact hello@musicata.io.

7. Error Codes

All errors use RFC 7807 Problem Details format with Content-Type: application/problem+json:

{
  "type": "https://api.musicata.io/errors/artist-not-found",
  "title": "Artist Not Found",
  "status": 404,
  "detail": "No artist with number MUS-999999 is enrolled in Bandshare.",
  "instance": "/api/v1/bandshare/artists/MUS-999999",
  "request_id": "req_01JP4X5K8M3N2Q7"
}

Status	Type	When
400	`bad-request`	Malformed JSON or missing required field
401	`unauthorized`	No `Authorization` header provided
401	`invalid-api-key`	Key not found, deactivated, or expired
403	`insufficient-scope`	Key valid but lacks the required scope
403	`ip-not-allowed`	Request from IP not in the key's allowlist
404	`artist-not-found`	Artist number not found or not enrolled
422	`validation-error`	Invalid parameters (includes `errors` array)
429	`rate-limit-exceeded`	Hourly limit exceeded. Check `Retry-After` header
500	`internal-error`	Unexpected server error. No internal details exposed

Every error response includes request_id for correlation with server logs. Share this ID when reporting issues.

8. Polling Guidance

Use Case	Recommended Interval	Endpoint
Full artist sync	Every 5 minutes	`GET /artists?updated_since=...`
Single artist check	Every 5 minutes	`GET /artists/:artistNumber`
Batch reconciliation	Every 15 minutes	`POST /artists/lookup`
Trust score history	Once daily	`GET /artists/:id/trust-history`

Delta sync: Use the updated_since parameter on the list endpoint to only fetch artists whose data has changed since your last sync. This dramatically reduces response size and processing time.

Trust scores are calculated once daily (01:00 UTC). Polling trust history more than once per day is unnecessary.

9. Changelog

v1.0 2026-02-19

Initial release. Artist profiles, list, bulk lookup, trust history, usage endpoints.

Breaking Change Policy

Adding new fields to a response is never a breaking change.
Removing fields, changing types, or altering status codes is a breaking change.
Breaking changes require a new API version (/v2/) with minimum 90 days deprecation notice.
Deprecated versions return Deprecation: true and Sunset headers per RFC 8594.

Music Intel Ltd, Folkestone, Kent, UK

Questions? hello@musicata.io