{
  "openapi": "3.1.0",
  "info": {
    "title": "Creators Toolbox API",
    "version": "1.0.0",
    "description": "Companies, tools and resources in the creator economy, plus a typed feed of what they ship, raise and buy. Built for teams making analytics products, developer tools and media about this market.\n\nAuthenticate with a bearer token. Create a free key with `POST /api/v1/keys`.",
    "contact": {
      "name": "Creators Toolbox",
      "url": "https://creatorstoolbox.com"
    }
  },
  "servers": [
    {
      "url": "https://creatorstoolbox.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Events",
      "description": "The feed: funding, product, acquisitions, hiring, editorial."
    },
    {
      "name": "Companies",
      "description": "Screen and read the catalog."
    },
    {
      "name": "Logos",
      "description": "Reviewed publisher logos and bounded identity lookup."
    },
    {
      "name": "Meta",
      "description": "Facets, counts and key issuance."
    },
    {
      "name": "News",
      "description": "Evidence, revisions, replay and source health."
    }
  ],
  "paths": {
    "/api/v1/logos": {
      "get": {
        "tags": [
          "Logos"
        ],
        "summary": "Look up reviewed logos by exact domain or entity",
        "description": "No DNS discovery, arbitrary source fetching, placeholders or parent-domain fallback. Select exactly one domain/entity. See /logo-api.md for staged/public delivery, size and freshness semantics.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 253,
              "description": "Exact public domain only, not a URL. No www stripping, DNS discovery or parent-domain fallback."
            }
          },
          {
            "name": "entity",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120,
              "description": "Stable entity ID instead of domain. Supply exactly one selector."
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "auto",
                "icon",
                "symbol",
                "wordmark"
              ]
            }
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "png",
                "webp",
                "svg",
                "original"
              ]
            }
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                32,
                64,
                128,
                256,
                512
              ],
              "description": "PNG/WebP long edge in pixels; aspect ratio retained. No raster upscaling. Omit for original/SVG."
            }
          },
          {
            "name": "freshness",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "allow_stale",
                "fresh_only"
              ]
            }
          },
          {
            "name": "on_missing",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "404"
              ],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Explicit verified, missing, unavailable-variant or review-required result. HTTP200 alone does not mean a genuine logo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "status",
                        "genuine_logo",
                        "entity",
                        "selected"
                      ],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "verified",
                            "stale",
                            "verification_time_unknown",
                            "not_found",
                            "variant_unavailable",
                            "review_required"
                          ]
                        },
                        "genuine_logo": {
                          "type": "boolean"
                        },
                        "normalized_domain": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "entity": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "company": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "selected": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "url": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "uri"
                            },
                            "public_original_url": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "uri"
                            },
                            "delivery_path": {
                              "type": "string"
                            },
                            "delivery_status": {
                              "type": "string",
                              "enum": [
                                "integrity_checked_endpoint",
                                "public_original_verified",
                                "staged_endpoint"
                              ]
                            },
                            "kind": {
                              "type": "string",
                              "enum": [
                                "icon",
                                "symbol",
                                "wordmark"
                              ]
                            },
                            "theme": {
                              "type": "string",
                              "enum": [
                                "light",
                                "dark",
                                "any"
                              ]
                            },
                            "format": {
                              "type": "string",
                              "enum": [
                                "svg",
                                "png",
                                "webp",
                                "jpg"
                              ]
                            },
                            "width": {
                              "type": "integer"
                            },
                            "height": {
                              "type": "integer"
                            },
                            "minimum_render_height": {
                              "type": "integer",
                              "minimum": 1,
                              "description": "Publisher minimum display height; do not downscale below this height."
                            },
                            "sha256": {
                              "type": "string"
                            },
                            "source_vector": {
                              "type": "boolean"
                            },
                            "source_url": {
                              "type": "string",
                              "format": "uri"
                            },
                            "source_page": {
                              "type": "string",
                              "format": "uri"
                            },
                            "license": {
                              "type": "object"
                            }
                          }
                        },
                        "freshness": {
                          "type": "object",
                          "properties": {
                            "state": {
                              "enum": [
                                "fresh",
                                "stale",
                                "unknown"
                              ]
                            },
                            "verified_at": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "review_due_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "correction_history": {
                          "type": "array",
                          "maxItems": 10,
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "entity_id",
                              "action",
                              "recorded_at",
                              "reason",
                              "evidence_url",
                              "reviewer"
                            ]
                          }
                        },
                        "available": {
                          "type": "array",
                          "maxItems": 8,
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "registry_version": {
                          "type": "string"
                        },
                        "discovery": {
                          "const": "reviewed_registry_only"
                        },
                        "automatic_refresh": {
                          "const": false
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Metadata ETag unchanged; authentication and quota still apply."
          },
          "400": {
            "description": "Invalid public domain or query."
          },
          "401": {
            "description": "API key required."
          },
          "404": {
            "description": "Explicit missing result when on_missing=404."
          },
          "429": {
            "description": "Existing API quota exceeded."
          }
        }
      }
    },
    "/api/v1/logos/search": {
      "get": {
        "tags": [
          "Logos"
        ],
        "summary": "Find reviewed identity candidates",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 80
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Explicit verified, missing, unavailable-variant or review-required result. HTTP200 alone does not mean a genuine logo.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "status",
                        "candidates",
                        "has_more"
                      ],
                      "properties": {
                        "status": {
                          "enum": [
                            "candidates",
                            "not_found"
                          ]
                        },
                        "candidates": {
                          "type": "array",
                          "maxItems": 10,
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "name",
                              "domains"
                            ],
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "domains": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Metadata ETag unchanged; authentication and quota still apply."
          },
          "400": {
            "description": "Invalid public domain or query."
          },
          "401": {
            "description": "API key required."
          },
          "404": {
            "description": "Explicit missing result when on_missing=404."
          },
          "429": {
            "description": "Existing API quota exceeded."
          }
        }
      }
    },
    "/api/v1/logos/assets/{key}": {
      "get": {
        "tags": [
          "Logos"
        ],
        "summary": "Read an immutable reviewed image from the static asset binding",
        "description": "Cloudflare image delivery. Public read-only fixed registry paths; no arbitrary URLs or runtime transforms. Original bytes or deterministic local renditions are integrity checked before serving. Public availability is not asserted until deployment verification.",
        "security": [],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}\\.(png|webp|svg|jpg)$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Image bytes with SHA-256 ETag, nosniff, CSP and a one-day immutable cache lifetime.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "304": {
            "description": "Matching ETag, no body."
          },
          "404": {
            "description": "Unknown asset."
          },
          "503": {
            "description": "Missing, corrupted, redirected or invalid static asset. Not cached."
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Service index",
        "security": [],
        "responses": {
          "200": {
            "description": "Endpoint list and auth instructions."
          }
        }
      }
    },
    "/api/v1/meta": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Facets and counts",
        "description": "Every category, subcategory, tag, persona, pricing tier, country and event type with its count. No key required \u2014 use it to build filter UIs.",
        "security": [],
        "responses": {
          "200": {
            "description": "Facets, counts and the sort keys each collection accepts."
          }
        }
      }
    },
    "/api/v1/keys": {
      "post": {
        "tags": [
          "Meta"
        ],
        "summary": "Create a free API key",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The key, shown once. Free tier allows 1,000 requests per UTC day."
          },
          "400": {
            "description": "Invalid email."
          },
          "429": {
            "description": "This address already has three active keys."
          }
        }
      }
    },
    "/api/v1/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Feed of company updates",
        "description": "Reverse-chronological by default. Live launch submissions are merged in at request time; everything else comes from the build snapshot.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "Comma-separated: funding, acquisition, financials, partnership, pricing, hiring, product, editorial, launch.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "description": "company_news, blog, jobs, launches.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "company",
            "in": "query",
            "description": "Comma-separated company ids.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Substring match on headline, body and company name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "until",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "has_funding",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "min_amount",
            "in": "query",
            "description": "Minimum disclosed amount in the smallest whole currency unit (dollars).",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "published_at",
                "amount"
              ],
              "default": "published_at"
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "desc",
                "asc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PageMeta"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown or revoked key."
          },
          "429": {
            "description": "Daily quota exhausted."
          }
        }
      }
    },
    "/api/v1/events/{id}": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "One event",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The event."
          },
          "404": {
            "description": "No such event."
          }
        }
      }
    },
    "/api/v1/funding": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Funding rounds",
        "description": "Funding events only, with amount, round, valuation and investors parsed out of the announcement, plus totals for the whole filtered set in `meta.summary`.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "min_amount",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "published_at",
                "amount"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of funding events plus a summary."
          }
        }
      }
    },
    "/api/v1/companies": {
      "get": {
        "tags": [
          "Companies"
        ],
        "summary": "Screen companies",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subcategory",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "persona",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pricing",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "free, freemium, paid"
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "ISO 3166-1 alpha-2.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_popularity",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "launched_after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "launched_before",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "has_events",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "active_since",
            "in": "query",
            "description": "Only companies with an event on or after this date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "popularity",
                "name",
                "newest",
                "events",
                "last_event"
              ],
              "default": "popularity"
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "desc",
                "asc"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of companies.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Company"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PageMeta"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/companies/{id}": {
      "get": {
        "tags": [
          "Companies"
        ],
        "summary": "One company",
        "description": "The full record, including the long description, features, FAQs and the ten most recent events.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The company."
          },
          "404": {
            "description": "No such company."
          }
        }
      }
    },
    "/api/v1/companies/{id}/events": {
      "get": {
        "tags": [
          "Companies"
        ],
        "summary": "Every event for one company",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of events."
          }
        }
      }
    },
    "/api/v1/launches": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Live launch submissions",
        "responses": {
          "200": {
            "description": "A page of launches, shaped as events."
          }
        }
      }
    },
    "/api/v1/news": {
      "get": {
        "tags": [
          "News"
        ],
        "summary": "Search evidence-backed news",
        "description": "Staged capability: requires a compatible news ledger schema. Production rollout awaits a verified recovery checkpoint. Cloudflare durable news ledger. Source dates may be unknown; inspect review status and evidence before using claims. See /news-api.md for cursor and ingestion semantics.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "entity",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "published_since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "published_until",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "retracted"
              ]
            }
          },
          {
            "name": "review_status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "unreviewed",
                "reviewed",
                "disputed"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded data with ledger epoch, watermark and pagination metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 50,
                      "items": {
                        "$ref": "#/components/schemas/NewsBrandedRecord"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "branding_version": {
                          "type": "string"
                        },
                        "branding_semantics": {
                          "const": "current_registry_not_event_history"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Unknown event."
          },
          "409": {
            "description": "Cursor is ahead of restored ledger; reconcile explicitly."
          },
          "429": {
            "description": "API quota exceeded."
          },
          "503": {
            "description": "news_unavailable: ledger absent or schema version incompatible."
          }
        }
      }
    },
    "/api/v1/news/changes": {
      "get": {
        "tags": [
          "News"
        ],
        "summary": "Replay immutable news changes",
        "description": "Staged capability: requires a compatible news ledger schema. Production rollout awaits a verified recovery checkpoint. Cloudflare durable news ledger. Source dates may be unknown; inspect review status and evidence before using claims. See /news-api.md for cursor and ingestion semantics.",
        "parameters": [
          {
            "name": "entity",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded data with ledger epoch, watermark and pagination metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 50,
                      "items": {
                        "$ref": "#/components/schemas/NewsBrandedChange"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "branding_version": {
                          "type": "string"
                        },
                        "branding_semantics": {
                          "const": "current_registry_not_event_history"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Unknown event."
          },
          "409": {
            "description": "Cursor is ahead of restored ledger; reconcile explicitly."
          },
          "429": {
            "description": "API quota exceeded."
          },
          "503": {
            "description": "news_unavailable: ledger absent or schema version incompatible."
          }
        }
      }
    },
    "/api/v1/news/{id}": {
      "get": {
        "tags": [
          "News"
        ],
        "summary": "Read a news event and its evidence",
        "description": "Staged capability: requires a compatible news ledger schema. Production rollout awaits a verified recovery checkpoint. Cloudflare durable news ledger. Source dates may be unknown; inspect review status and evidence before using claims. See /news-api.md for cursor and ingestion semantics.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded data with ledger epoch, watermark and pagination metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "anyOf": [
                        {
                          "$ref": "#/components/schemas/NewsBrandedRecord"
                        },
                        {
                          "type": "array",
                          "maxItems": 50,
                          "items": {
                            "$ref": "#/components/schemas/NewsBrandedChange"
                          }
                        }
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "branding_version": {
                          "type": "string"
                        },
                        "branding_semantics": {
                          "const": "current_registry_not_event_history"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Unknown event."
          },
          "409": {
            "description": "Cursor is ahead of restored ledger; reconcile explicitly."
          },
          "429": {
            "description": "API quota exceeded."
          },
          "503": {
            "description": "news_unavailable: ledger absent or schema version incompatible."
          }
        }
      }
    },
    "/api/v1/news/{id}/history": {
      "get": {
        "tags": [
          "News"
        ],
        "summary": "Read compact immutable revisions",
        "description": "Staged capability: requires a compatible news ledger schema. Production rollout awaits a verified recovery checkpoint. Cloudflare durable news ledger. Source dates may be unknown; inspect review status and evidence before using claims. See /news-api.md for cursor and ingestion semantics.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded data with ledger epoch, watermark and pagination metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 50,
                      "items": {
                        "$ref": "#/components/schemas/NewsBrandedChange"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "branding_version": {
                          "type": "string"
                        },
                        "branding_semantics": {
                          "const": "current_registry_not_event_history"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Unknown event."
          },
          "409": {
            "description": "Cursor is ahead of restored ledger; reconcile explicitly."
          },
          "429": {
            "description": "API quota exceeded."
          },
          "503": {
            "description": "news_unavailable: ledger absent or schema version incompatible."
          }
        }
      }
    },
    "/api/v1/news/sources": {
      "get": {
        "tags": [
          "News"
        ],
        "summary": "Inspect registered source health",
        "description": "Staged capability: requires a compatible news ledger schema. Production rollout awaits a verified recovery checkpoint. Cloudflare durable news ledger. Source dates may be unknown; inspect review status and evidence before using claims. See /news-api.md for cursor and ingestion semantics.",
        "parameters": [
          {
            "name": "entity",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded data with ledger epoch, watermark and pagination metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "maxItems": 50,
                      "items": {
                        "$ref": "#/components/schemas/NewsBrandedRecord"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "branding_version": {
                          "type": "string"
                        },
                        "branding_semantics": {
                          "const": "current_registry_not_event_history"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Unknown event."
          },
          "409": {
            "description": "Cursor is ahead of restored ledger; reconcile explicitly."
          },
          "429": {
            "description": "API quota exceeded."
          },
          "503": {
            "description": "news_unavailable: ledger absent or schema version incompatible."
          }
        }
      }
    },
    "/api/v1/news/quality": {
      "get": {
        "tags": [
          "News"
        ],
        "summary": "Read measured quality counters",
        "description": "Staged capability: requires a compatible news ledger schema. Production rollout awaits a verified recovery checkpoint. Cloudflare durable news ledger. Source dates may be unknown; inspect review status and evidence before using claims. See /news-api.md for cursor and ingestion semantics.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bounded data with ledger epoch, watermark and pagination metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {},
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "404": {
            "description": "Unknown event."
          },
          "409": {
            "description": "Cursor is ahead of restored ledger; reconcile explicitly."
          },
          "429": {
            "description": "API quota exceeded."
          },
          "503": {
            "description": "news_unavailable: ledger absent or schema version incompatible."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your key from POST /api/v1/keys. `X-Api-Key` is accepted too."
      }
    },
    "schemas": {
      "PageMeta": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Rows on this page."
          },
          "total": {
            "type": "integer",
            "description": "Rows matching the filter."
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the snapshot behind this response was built."
          }
        }
      },
      "CompanyStub": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "domain": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "logo": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Company": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "about": {
            "type": [
              "string",
              "null"
            ],
            "description": "Long description. Detail endpoint only."
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "subcategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "pricing": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "Free",
              "Freemium",
              "Paid",
              null
            ]
          },
          "popularity": {
            "type": [
              "integer",
              "null"
            ],
            "description": "0-100 editorial score."
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "domain": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "logo": {
            "type": [
              "string",
              "null"
            ]
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "launched_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "url": {
            "type": "string",
            "description": "The listing page on Creators Toolbox."
          },
          "event_count": {
            "type": "integer"
          },
          "last_event_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          }
        }
      },
      "Funding": {
        "type": "object",
        "properties": {
          "amount": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Round size in whole currency units."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "round": {
            "type": [
              "string",
              "null"
            ],
            "description": "Seed, Series A, and so on."
          },
          "valuation": {
            "type": [
              "integer",
              "null"
            ]
          },
          "investors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "lead",
                    "participant",
                    "investor"
                  ]
                }
              }
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "funding",
              "acquisition",
              "financials",
              "partnership",
              "pricing",
              "hiring",
              "product",
              "editorial",
              "launch",
              "other"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "company_news",
              "blog",
              "jobs",
              "launches"
            ]
          },
          "company_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "company": {
            "$ref": "#/components/schemas/CompanyStub"
          },
          "also_about": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Other company ids this story concerns."
          },
          "headline": {
            "type": "string"
          },
          "body": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "url": {
            "type": "string"
          },
          "source_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "The company's own announcement."
          },
          "discussion_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          },
          "funding": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Funding"
              },
              {
                "type": "null"
              }
            ]
          },
          "deal": {
            "type": [
              "object",
              "null"
            ],
            "description": "Disclosed price on an acquisition.",
            "properties": {
              "amount": {
                "type": "integer"
              },
              "currency": {
                "type": "string"
              }
            }
          }
        }
      },
      "NewsLogo": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "asset_id",
          "url",
          "asset_path",
          "sha256",
          "media_type",
          "width",
          "height",
          "vector",
          "theme",
          "source_url",
          "source_page",
          "verified_at",
          "verification_method",
          "license",
          "hosting_status",
          "hosted_verified_at",
          "hosted_sha256"
        ],
        "properties": {
          "asset_id": {
            "type": "string",
            "pattern": "^logo_[a-f0-9]{64}$"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Verified Creators Toolbox hosted URL only. Null for staged assets or unverified hosting; source_url is provenance, not a serving fallback."
          },
          "asset_path": {
            "type": "string",
            "pattern": "^/images/logos/",
            "description": "Repository asset path. Does not establish public availability."
          },
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "media_type": {
            "type": "string",
            "enum": [
              "image/svg+xml",
              "image/png",
              "image/jpeg",
              "image/webp"
            ]
          },
          "width": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8192
          },
          "height": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8192
          },
          "vector": {
            "type": "boolean"
          },
          "theme": {
            "type": "string",
            "enum": [
              "light",
              "dark",
              "any"
            ],
            "description": "Required background theme; preserve original colors."
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://"
          },
          "source_page": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://"
          },
          "verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "verification_method": {
            "const": "publisher_brand_asset_and_bytes_review"
          },
          "license": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "url",
              "usage_notes",
              "attribution"
            ],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "usage_notes": {
                "type": "string"
              },
              "attribution": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "hosting_status": {
            "type": "string",
            "enum": [
              "staged",
              "unverified",
              "verified"
            ]
          },
          "hosted_verified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "hosted_sha256": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "NewsBrand": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "kind",
          "website",
          "identity_source_url",
          "identity_verified_at",
          "logo"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "company",
              "product",
              "project"
            ]
          },
          "website": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://"
          },
          "identity_source_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://"
          },
          "identity_verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "logo": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/NewsLogo"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "NewsBranding": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "entity",
          "company"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/NewsBrand"
          },
          "company": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/NewsBrand"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "description": "Current reviewed identity metadata. Company is the explicitly mapped parent, never a substitute for a missing product logo. A company entity has company=null."
      },
      "NewsBrandedRecord": {
        "type": "object",
        "required": [
          "branding"
        ],
        "properties": {
          "branding": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/NewsBranding"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "NewsBrandedChange": {
        "type": "object",
        "required": [
          "event"
        ],
        "properties": {
          "event": {
            "$ref": "#/components/schemas/NewsBrandedRecord"
          }
        }
      }
    }
  }
}