{
  "openapi": "3.0.3",
  "info": {
    "title": "Cast Index Pro API",
    "version": "1.0.0",
    "description": "A read-only, versioned JSON/CSV feed over The Cast Index's editorial dataset — the same rankings, profiles, events and evidence published on the public site, structured for programmatic use. Public endpoints (this document included) are open for evaluation; Pro and Studio unlock higher rate limits, alerting, and a support desk. No endpoint here can be used to influence the ranking itself — see /methodology.",
    "contact": { "name": "Cast Index Pro desk", "email": "pro@thecastindex.com", "url": "https://thecastindex.com/pro" },
    "license": { "name": "Cast Index Pro / Studio terms", "url": "https://thecastindex.com/legal/terms" }
  },
  "servers": [{ "url": "https://thecastindex.com/api/v1", "description": "Production (static, versioned)" }],
  "tags": [
    { "name": "rankings", "description": "The numbered Global 100" },
    { "name": "rising", "description": "The unnumbered Rising board" },
    { "name": "models", "description": "Full per-model detail" },
    { "name": "creatives", "description": "Makeup, hair, styling, photography, casting, creative direction" },
    { "name": "agencies", "description": "Agency rosters" },
    { "name": "events", "description": "Real fashion weeks" },
    { "name": "momentum", "description": "Dated, sourced activity evidence" },
    { "name": "alerts", "description": "Scouting alerts feed" },
    { "name": "export", "description": "Flat CSV export" }
  ],
  "paths": {
    "/index.json": {
      "get": { "summary": "API index", "description": "Lists every available endpoint with its live path and current record count.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } } } }
    },
    "/rankings.json": {
      "get": { "tags": ["rankings"], "summary": "The numbered Global 100", "description": "One record per ranked model, in rank order. Mirrors thecastindex.com/rankings.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingsResponse" } } } } } }
    },
    "/rising.json": {
      "get": { "tags": ["rising"], "summary": "The Rising board", "description": "Unnumbered watch profiles tracked ahead of a Global 100 entry. Mirrors thecastindex.com/rising.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RisingResponse" } } } } } }
    },
    "/models/{slug}.json": {
      "get": {
        "tags": ["models"], "summary": "Full detail for one model",
        "description": "Includes score breakdown, evidence, sources, and — where an editorial deep profile has been reviewed — quick facts and full biography sections.",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "anok-yai" }],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDetailResponse" } } } },
          "404": { "description": "No model with that slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFound" } } } }
        }
      }
    },
    "/creatives.json": {
      "get": { "tags": ["creatives"], "summary": "Creatives directory", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreativesResponse" } } } } } }
    },
    "/agencies.json": {
      "get": { "tags": ["agencies"], "summary": "Agencies derived from Global 100 rosters", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgenciesResponse" } } } } } }
    },
    "/events.json": {
      "get": { "tags": ["events"], "summary": "Real fashion weeks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" } } } } } }
    },
    "/momentum.json": {
      "get": {
        "tags": ["momentum"], "summary": "Dated, sourced activity evidence per Global 100 model",
        "description": "IMPORTANT: this is not a synthetic week-over-week score history. The Cast Index publishes one reviewed editorial snapshot per profile, not a database of past snapshots. Every entry here is the same dated, sourced evidence already published on the model's public profile page.",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MomentumResponse" } } } } }
      }
    },
    "/alerts.json": {
      "get": {
        "tags": ["alerts"], "summary": "Scouting alerts feed",
        "description": "Every current Rising board entry, plus the single strongest sourced signal for each high-confidence Global 100 name. Poll on your own schedule and diff against your last pull — this is not a push/webhook notification.",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertsResponse" } } } } }
      }
    },
    "/export.csv": {
      "get": { "tags": ["export"], "summary": "Global 100 + Rising board as CSV", "description": "One row per model. `cohort` is `global_100` or `rising`; score columns are blank for Rising rows, which are not numerically scored.", "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" } } } } } }
    }
  },
  "components": {
    "schemas": {
      "ApiMeta": {
        "type": "object",
        "properties": {
          "source": { "type": "string", "example": "The Cast Index" },
          "editionUpdated": { "type": "string", "format": "date", "example": "2026-07-13" },
          "license": { "type": "string" },
          "documentation": { "type": "string", "format": "uri" },
          "endpoint": { "type": "string" },
          "count": { "type": "integer" },
          "description": { "type": "string" },
          "honesty_note": { "type": "string", "description": "Present on /momentum.json and /alerts.json — an explicit disclosure of what the endpoint is not (e.g. not a synthetic time series, not a push notification)." },
          "slug": { "type": "string", "description": "Present on /models/{slug}.json only — echoes the requested slug." }
        }
      },
      "ApiIndex": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "method": { "type": "string" }, "description": { "type": "string" }, "count": { "type": "integer" } } } } } },
      "ScoreBreakdown": { "type": "object", "properties": { "runway": { "type": "number" }, "campaigns": { "type": "number" }, "editorial": { "type": "number" }, "cultural": { "type": "number" } }, "description": "Weighted 40 / 30 / 20 / 10 to produce `score`. See /methodology." },
      "RankingRecord": {
        "type": "object",
        "properties": {
          "rank": { "type": "integer", "example": 1 },
          "slug": { "type": "string", "example": "anok-yai" },
          "name": { "type": "string", "example": "Anok Yai" },
          "score": { "type": "number", "example": 97.5 },
          "scoreLabel": { "type": "string", "example": "97.5/100" },
          "scoreBreakdown": { "$ref": "#/components/schemas/ScoreBreakdown" },
          "confidence": { "type": "string", "enum": ["high", "medium", "baseline"] },
          "auditLabel": { "type": "string" },
          "country": { "type": "string" },
          "region": { "type": "string", "enum": ["asian", "african", "european", "latin-american", "north-american", "oceanian"] },
          "agencies": { "type": "array", "items": { "type": "string" } },
          "eventSlugs": { "type": "array", "items": { "type": "string" } },
          "profileUrl": { "type": "string", "format": "uri" }
        }
      },
      "RankingsResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "rankings": { "type": "array", "items": { "$ref": "#/components/schemas/RankingRecord" } } } },
      "RisingRecord": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "name": { "type": "string" }, "nationality": { "type": "string" }, "region": { "type": "string" },
          "agency": { "type": "string" }, "specialty": { "type": "string" }, "spottedAtEvent": { "type": ["string", "null"] },
          "note": { "type": "string" }, "profileUrl": { "type": "string", "format": "uri" }, "sourceUrl": { "type": "string", "format": "uri" }
        }
      },
      "RisingResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "rising": { "type": "array", "items": { "$ref": "#/components/schemas/RisingRecord" } } } },
      "ModelDetailRecord": {
        "allOf": [
          { "$ref": "#/components/schemas/RankingRecord" },
          {
            "type": "object",
            "properties": {
              "descriptor": { "type": "string" }, "bio": { "type": "string" }, "notableFor": { "type": "string" }, "wiki": { "type": "string", "format": "uri" },
              "evidence": { "type": "array", "items": { "type": "object", "properties": { "note": { "type": "string" } } } },
              "sources": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } },
              "deepProfile": {
                "type": ["object", "null"],
                "properties": {
                  "lastReviewed": { "type": "string", "format": "date" },
                  "quickFacts": { "type": "array", "items": { "type": "string" } },
                  "sections": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": "string" }, "paragraphs": { "type": "array", "items": { "type": "string" } } } } }
                }
              }
            }
          }
        ]
      },
      "ModelDetailResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "model": { "$ref": "#/components/schemas/ModelDetailRecord" } } },
      "NotFound": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "error": { "type": "string", "example": "not_found" } } },
      "CreativeRecord": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "name": { "type": "string" }, "discipline": { "type": "string" }, "disciplineLabel": { "type": "string" },
          "based": { "type": "string" }, "country": { "type": "string" }, "knownFor": { "type": "string" }, "signature": { "type": "string" },
          "eventSlugs": { "type": "array", "items": { "type": "string" } }, "wiki": { "type": "string", "format": "uri" }, "profileUrl": { "type": "string", "format": "uri" },
          "deepProfile": { "type": ["object", "null"], "properties": { "lastReviewed": { "type": "string" }, "quickFacts": { "type": "array", "items": { "type": "string" } } } }
        }
      },
      "CreativesResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/CreativeRecord" } } } },
      "AgencyRecord": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "rosterCount": { "type": "integer" },
          "roster": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" } } } },
          "profileUrl": { "type": "string", "format": "uri" }
        }
      },
      "AgenciesResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "agencies": { "type": "array", "items": { "$ref": "#/components/schemas/AgencyRecord" } } } },
      "EventRecord": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "region": { "type": "string" },
          "season": { "type": "string" }, "year": { "type": "integer" }, "dates": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" },
          "venue": { "type": "string" }, "status": { "type": "string", "enum": ["live", "upcoming", "complete"] }, "tier": { "type": "string", "enum": ["established", "emerging", "watchlist"] },
          "brands": { "type": "array", "items": { "type": "string" } }, "profileUrl": { "type": "string", "format": "uri" },
          "deepProfile": { "type": ["object", "null"], "properties": { "lastReviewed": { "type": "string" }, "quickFacts": { "type": "array", "items": { "type": "string" } } } }
        }
      },
      "EventsResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventRecord" } } } },
      "MomentumRecord": {
        "type": "object",
        "properties": {
          "rank": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "score": { "type": "number" }, "confidence": { "type": "string" },
          "evidence": { "type": "array", "items": { "type": "object", "properties": { "note": { "type": "string" } } } },
          "sources": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } },
          "recentRecord": { "type": ["array", "null"], "items": { "type": "string" } },
          "profileUrl": { "type": "string", "format": "uri" }
        }
      },
      "MomentumResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "momentum": { "type": "array", "items": { "$ref": "#/components/schemas/MomentumRecord" } } } },
      "AlertRecord": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "enum": ["rising_entry", "tier_signal"] }, "slug": { "type": "string" }, "name": { "type": "string" },
          "headline": { "type": "string" }, "detail": { "type": "string" }, "sourceUrl": { "type": ["string", "null"], "format": "uri" }, "profileUrl": { "type": "string", "format": "uri" }
        }
      },
      "AlertsResponse": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/ApiMeta" }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRecord" } } } }
    }
  }
}