Skip to content

Taste

Summarize Brendan’s public movie and TV recommendations

GET /api/taste/summary.json

Returns complete-corpus counts, type, genre, release-decade, and director distributions with coverage plus deterministic illustrative examples. Examples are not a statistical sample. A public miss or absence does not establish private viewing or save history.

Markdown · Authoritative OpenAPI

Request policy

Operation
summarizeTasteCollection
Access
anonymous
Automatic retries
None
Redirects
Returned to the caller without following
Request body limit
No request body
Pagination
No collection iterator

Parameters

collection string required

Approved public collection to summarize. Version 1 supports movies only.

Allowed: "movies"

exampleLimit number

Number of deterministic illustrative examples.

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

Complete public movie recommendation summary

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
      ]
    }
  },
  "ETag": {
    "description": "Entity tag for conditional requests",
    "schema": {
      "type": "string"
    }
  },
  "Last-Modified": {
    "description": "Last modification date (HTTP IMF-fixdate)",
    "schema": {
      "type": "string",
      "pattern": "^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$",
      "examples": [
        "Sun, 06 Sep 2026 17:40:13 GMT"
      ]
    }
  },
  "Cache-Control": {
    "description": "Caching directives",
    "schema": {
      "type": "string"
    }
  },
  "X-Total-Count": {
    "description": "Total number of items",
    "schema": {
      "type": "integer"
    }
  },
  "Link": {
    "description": "RFC 8288 Web Linking header with pagination links",
    "schema": {
      "type": "string"
    }
  },
  "Link-Template": {
    "description": "RFC 9652 Link-Template header with query parameter templates",
    "schema": {
      "type": "string"
    }
  },
  "Deprecation": {
    "description": "RFC 9745 lifecycle deprecation signal",
    "schema": {
      "type": "string"
    }
  },
  "Sunset": {
    "description": "RFC 8594 lifecycle sunset date (HTTP IMF-fixdate)",
    "schema": {
      "type": "string",
      "pattern": "^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$",
      "examples": [
        "Sun, 06 Sep 2026 17:40:13 GMT"
      ]
    }
  }
}

application/json

TasteCollectionSummaryV1

Schema details

schemaVersion unknown required

outcome string required

Allowed: "ok" | "empty_collection"

summary string required

scope object required

Schema details

visibility unknown required

corpusId string required

label string required

definition string required

inclusionRules string[] required

Schema details

string

exclusionMeaning string required

canonicalUrl string required (uri)

counts object required

Schema details

returnedCount number required

collectionCount number required

coverage object required

Schema details

dataAsOf string required

Schema details

string (date-time)

unknown

dimensions object[] required

Schema details

object

Schema details

dimension string required

Allowed: "type" | "genre" | "releaseDecade" | "director"

eligibleCount number required

populatedCount number required

missingCount number required

distributions object[] required

Schema details

object

Schema details

dimension string required

Allowed: "type" | "genre" | "releaseDecade" | "director"

label string required

multiValue boolean required

denominator unknown required

denominatorCount number required

values object[] required

Schema details

object

Schema details

value string required

label string required

count number required

shareOfEligible number required

examples object[] required

Schema details

object

Schema details

canonicalId string required

collection string required

title string required

canonicalUrl string required (uri)

description string required

evidence string[] required

Schema details

string

evidenceDetails object[] required

Schema details

object

Schema details

code string required

Allowed: "public-corpus-membership" | "exact-title-match" | "partial-title-match" | "genre-constraint-match" | "director-constraint-match" | "semantic-candidate-rehydrated" | "summary.genre-example" | "summary.director-example" | "summary.type-example" | "summary.decade-example"

text string required

fields string[] required

Schema details

string

data object required

selection object required

Schema details

task unknown required

method unknown required

role unknown required

supportsPopulationClaims unknown required

explanation string required

generatedAt string required (date-time)

renderInput object required

Schema details

canonicalIds string[] required

Schema details

string

304

Not Modified

400

Unsupported collection or invalid example 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

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

Summary 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 GET 'https://irvinebroque.com/api/taste/summary.json?collection=movies' --header 'Accept: application/json'

TypeScript

import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.taste.summary({
  "collection": "movies"
});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.

CLI

irvinebroque taste summary --collection 'movies'

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.