Responses

Single resources use a response object with data.

interface Single<T extends Resource> {
  data: T;
}

Example:

{
  "data": {
    "id": "artist_123",
    "type": "artist",
    "attributes": {
      "name": "Example Artist"
    }
  }
}

Lists use data and meta. Lookup collections use data.

List

interface List<T extends Resource> {
  data: T[];
  meta: {
    limit: number;
    offset: number;
    total?: number;
  };
}

Use lists for normal list endpoints and relationship endpoints.

The usual maximum limit is 100.

interface Collection<T extends Resource> {
  data: T[];
}

Collections are used by lookup endpoints. Returned resources keep the request order. Missing ids are omitted from data.

GET /, GET /search, GET /search/suggestions, and GET /explore return their model directly, without a data wrapper.

Errors always use the shared error envelope:

interface ErrorResponse {
  error: {
    status: number;
    message: string;
    details?: ErrorDetail[];
    requestId?: string;
  };
}