Skip to content

Music

Compare a portable listener profile with Brendan’s canonical tracks

POST /api/music/intersections.json

Read-only bounded structured query. The UTF-8 request body is limited to 32768 bytes, is not retained, and returns grounded canonical IDs with reason codes rather than a compatibility percentage.

Markdown · Authoritative OpenAPI

Request policy

Operation
intersectMusicTaste
Access
anonymous
Automatic retries
None
Redirects
Returned to the caller without following
Request body limit
32768 UTF-8 bytes
Pagination
No collection iterator

Parameters

No path or query parameters.

Request body

application/json

MusicIntersectionRequestV1 required

Schema details

profile object required

Schema details

schemaVersion unknown required

subject object

Schema details

canonicalUrl string

displayName string

music object required

Schema details

artists object[] required

Schema details

object

Schema details

name string required

stance string

Allowed: "love" | "like" | "curious" | "avoid"

weight number

externalIds object

Schema details

spotify-artist string

recordings object[] required

Schema details

object

Schema details

title string required

artist string required

stance string

Allowed: "love" | "like" | "curious" | "avoid"

weight number

externalIds object

Schema details

isrc string

spotify-track string

albums object[] required

Schema details

object

Schema details

title string required

artist string required

stance string

Allowed: "love" | "like" | "curious" | "avoid"

weight number

externalIds object

Schema details

discogs-master string

discogs-release string

genres object[] required

Schema details

object

Schema details

name string required

stance string

Allowed: "love" | "like" | "curious" | "avoid"

weight number

notes string[] required

Schema details

string

limit number

Request headers

  • API-Version (optional) — Header-based API version selection. Omit it, send an empty value, or send 1.0.0; surrounding whitespace is ignored.
  • Idempotency-Key (optional) — Accepted for clients that attach a key uniformly. GET, HEAD, and OPTIONS are already safe and intrinsically idempotent, so read responses are not stored in an idempotency replay cache.

Responses

200

Grounded music intersection result

Response headers
{
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  }
}

application/json

MusicIntersectionResultV1

Schema details

summary string required

matches object[] required

Schema details

object

Schema details

canonicalId string required

score number required

reasons object[] required

Schema details

object

Schema details

code string required

Allowed: "recording-id" | "recording-name" | "artist-id" | "artist-name" | "album-id" | "album-name" | "genre" | "semantic" | "avoid"

label string required

strength number required

unmatched object required

Schema details

artists number required

recordings number required

albums number required

genres number required

truncated boolean required

400

Invalid profile or request

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

413

Request exceeds the 32 KiB limit

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

415

Content-Type is not application/json

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

429

Public REST request limit exceeded

Response headers
{
  "Retry-After": {
    "description": "Seconds before the request should be retried",
    "schema": {
      "type": "integer",
      "enum": [
        60
      ]
    }
  },
  "RateLimit": {
    "description": "Current quota state for the exhausted public-rest policy",
    "schema": {
      "type": "string"
    }
  },
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  }
}

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

503

Intersection service unavailable

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

Examples

Examples use synthetic fixture values. Replace fixture identifiers with public IDs returned by the service. Request bodies and precise locations are transient; keep them out of logs.

curl

curl --fail-with-body --max-time 30 --max-filesize 16777216 --request POST 'https://irvinebroque.com/api/music/intersections.json' --header 'Accept: application/json' --header 'Content-Type: application/json' --data-binary @request.json

TypeScript

import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.music.intersect({
  "body": {
    "profile": {
      "schemaVersion": "1",
      "music": {
        "artists": [],
        "recordings": [],
        "albums": [],
        "genres": [],
        "notes": []
      }
    }
  }
});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.

CLI

irvinebroque music intersect --body-file request.json

request.json

{
  "profile": {
    "schemaVersion": "1",
    "music": {
      "artists": [],
      "recordings": [],
      "albums": [],
      "genres": [],
      "notes": []
    }
  }
}

The SDK preserves status, headers, and the server envelope. A 304 has no fresh body. Errors retain structured problem details; ordinary error messages omit response details. Responses are limited to 16 MiB and requests time out after 30 seconds by default.