# Build a deterministic personalized queue from Brendan’s canonical tracks

Read-only bounded structured query over the playable collection. The UTF-8 request body is limited to 24576 bytes. Inputs are canonical affinities, direct votes, recent tracks, optional intent, closed local context, and optional version-1 continuation (up to 120 timestamped plays, 12 buffered canonical IDs, and sequence position). All track attributes are rehydrated from D1; the server retains no listener state. Legacy requests without continuation retain their response shape and hard recency exclusions. Continuation responses additionally report cooldown relaxation and applied context signals.

Operation: buildMusicStation
POST /api/music/station.json

Access: anonymous. Automatic retries: none. Redirects: manual. Request body limit: 24576 bytes.
Default timeout: 30 seconds. Response limit: 16 MiB. Pagination is opt-in and bounded; an exhausted bound reports incomplete execution.

[HTML reference](/developers/api/buildMusicStation) · [Authoritative schemas](/api/openapi.json)

## Wire contract

```json
{
  "operationId": "buildMusicStation",
  "summary": "Build a deterministic personalized queue from Brendan’s canonical tracks",
  "description": "Read-only bounded structured query over the playable collection. The UTF-8 request body is limited to 24576 bytes. Inputs are canonical affinities, direct votes, recent tracks, optional intent, closed local context, and optional version-1 continuation (up to 120 timestamped plays, 12 buffered canonical IDs, and sequence position). All track attributes are rehydrated from D1; the server retains no listener state. Legacy requests without continuation retain their response shape and hard recency exclusions. Continuation responses additionally report cooldown relaxation and applied context signals.",
  "tags": [
    "Music"
  ],
  "parameters": [
    {
      "name": "API-Version",
      "in": "header",
      "required": false,
      "description": "Header-based API version selection. Omit it, send an empty value, or send 1.0.0; surrounding whitespace is ignored.",
      "schema": {
        "type": "string",
        "pattern": "^[ \\t]*(1\\.0\\.0)?[ \\t]*$",
        "default": "1.0.0"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "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.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "x-idempotency": "read-only-structured-query",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MusicStationRequestV1"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canonical personalized queue, honest empty result, or bounded degraded fallback",
      "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
            ]
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicStationResultV1"
          }
        }
      }
    },
    "400": {
      "description": "Invalid station request",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "413": {
      "description": "Request exceeds the 24 KiB limit",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "415": {
      "description": "Content-Type is not application/json",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "429": {
      "description": "Public REST request limit exceeded",
      "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
            ]
          }
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    },
    "503": {
      "description": "Station service unavailable",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ProblemDetails"
          }
        }
      }
    }
  }
}
```

## Synthetic examples

### curl

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

### TypeScript

```typescript
import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.music.station({
  "body": {
    "schemaVersion": "1",
    "stationSeed": "fixture",
    "affinities": [],
    "votes": [],
    "hardExclusions": [],
    "recentCanonicalIds": []
  }
});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.
```

### CLI

```bash
irvinebroque music station --body-file request.json
```

### request.json

```json
{
  "schemaVersion": "1",
  "stationSeed": "fixture",
  "affinities": [],
  "votes": [],
  "hardExclusions": [],
  "recentCanonicalIds": []
}
```