{
  "openapi": "3.1.0",
  "info": {
    "title": "favi",
    "version": "1",
    "description": "Company logos by domain, name or stock ticker, plus brand data as JSON, on one publishable key. Misses serve a generated lettermark immediately (202) while the real logo is crawled — usually seconds. Subdomains inherit the registrable parent’s logo until they have their own. Free: 500,000 requests a month; Pro: 2,000,000 for $29. No attribution required. Over quota serves lettermarks, never errors."
  },
  "servers": [
    {
      "url": "https://img.favi.sh"
    }
  ],
  "externalDocs": {
    "url": "https://favi.sh/docs.md",
    "description": "The complete reference as Markdown (also /docs for HTML, /llms.txt for a summary)."
  },
  "paths": {
    "/{domain}": {
      "get": {
        "summary": "Logo for a domain",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "stripe.com"
          },
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Publishable API key (pk_…). `token` is accepted as an alias for logo.dev compatibility.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "webp",
                "png",
                "jpg",
                "avif"
              ]
            },
            "description": "webp default; avif is smaller again and keeps transparency; jpg flattens it onto white."
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ]
            },
            "description": "dark serves a white-recolored variant of dark transparent marks; colorful logos serve unchanged."
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 800
            },
            "description": "Downscale to fit. Never upscaled past the stored master (max 256px)."
          },
          {
            "name": "width",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Exact width (alias: w). Overrides size."
          },
          {
            "name": "height",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Exact height (alias: h). Overrides size."
          },
          {
            "name": "retina",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Double the requested dimensions."
          },
          {
            "name": "greyscale",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "fallback",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "404"
              ]
            },
            "description": "Return HTTP 404 on a miss instead of a generated lettermark."
          }
        ],
        "responses": {
          "200": {
            "description": "The stored logo (or, on auth/quota problems, a lettermark — never a broken image). x-favi-result header explains what was served.",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/avif": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "202": {
            "description": "Crawl in flight; body is a placeholder lettermark with a 30s cache. Retry after it lands.",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/avif": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Only with fallback=404: no real logo available."
          }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Name → domain autocomplete",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "stri"
          },
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Publishable API key (pk_…). `token` is accepted as an alias for logo.dev compatibility.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 8
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Best matches first: exact, then popularity.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "domain": {
                            "type": "string"
                          },
                          "logoUrl": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          }
        }
      }
    },
    "/brand/{domain}": {
      "get": {
        "summary": "Brand profile",
        "description": "Name, description, brand colors, blurhash, social links, and every logo URL variant for a domain. Unknown domains answer 202 {\"status\":\"pending\"} while the first crawl runs.",
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "stripe.com"
          },
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Publishable API key (pk_…). `token` is accepted as an alias for logo.dev compatibility.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The profile. Fields the site never published are null.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "description": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "brandColor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The first entry of colors that can carry a letter legibly — what the fallback mark is set on. Null when none can."
                    },
                    "colors": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "description": "Up to five colors read off the logo’s visible pixels, most prominent first. Near-white is omitted unless it is the only color. Null until the domain has been crawled since palettes were recorded.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "hex": {
                            "type": "string",
                            "example": "#635bff"
                          },
                          "r": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 255
                          },
                          "g": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 255
                          },
                          "b": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 255
                          },
                          "share": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "Fraction of the logo’s visible pixels in this color."
                          }
                        },
                        "required": [
                          "hex",
                          "r",
                          "g",
                          "b",
                          "share"
                        ]
                      }
                    },
                    "blurhash": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Blurhash of the logo flattened onto white, 4×3 components. Null until the domain has been crawled since it was recorded."
                    },
                    "socials": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "logos": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "image": {
                      "type": "object"
                    },
                    "lastCrawledAt": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "First crawl in flight; retry shortly."
          },
          "404": {
            "description": "No logo could be found, or the domain is blocked."
          }
        }
      }
    },
    "/name/{brand}": {
      "get": {
        "summary": "Logo by company name",
        "description": "Resolves the top search match and 302s to its /{domain} URL with the query string intact — every image parameter rides along.",
        "parameters": [
          {
            "name": "brand",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "Stripe"
          },
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Publishable API key (pk_…). `token` is accepted as an alias for logo.dev compatibility.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "webp",
                "png",
                "jpg",
                "avif"
              ]
            },
            "description": "webp default; avif is smaller again and keeps transparency; jpg flattens it onto white."
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ]
            },
            "description": "dark serves a white-recolored variant of dark transparent marks; colorful logos serve unchanged."
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 800
            },
            "description": "Downscale to fit. Never upscaled past the stored master (max 256px)."
          },
          {
            "name": "width",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Exact width (alias: w). Overrides size."
          },
          {
            "name": "height",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Exact height (alias: h). Overrides size."
          },
          {
            "name": "retina",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Double the requested dimensions."
          },
          {
            "name": "greyscale",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "fallback",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "404"
              ]
            },
            "description": "Return HTTP 404 on a miss instead of a generated lettermark."
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to the matched domain’s logo URL."
          }
        }
      }
    },
    "/ticker/{symbol}": {
      "get": {
        "summary": "Logo by stock ticker",
        "description": "Resolves an exchange listing to the company’s domain and 302s to its /{domain} URL with the query string intact. Bare symbols are US listings; other exchanges use the Yahoo-style suffix (SHOP.TO, 7203.T, AAPL.L). Listings come from Wikidata (all named exchanges) and the SEC (the complete US symbol list). An unknown ticker is never guessed into a domain.",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "AAPL"
          },
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Publishable API key (pk_…). `token` is accepted as an alias for logo.dev compatibility.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "webp",
                "png",
                "jpg",
                "avif"
              ]
            },
            "description": "webp default; avif is smaller again and keeps transparency; jpg flattens it onto white."
          },
          {
            "name": "theme",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ]
            },
            "description": "dark serves a white-recolored variant of dark transparent marks; colorful logos serve unchanged."
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 800
            },
            "description": "Downscale to fit. Never upscaled past the stored master (max 256px)."
          },
          {
            "name": "width",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Exact width (alias: w). Overrides size."
          },
          {
            "name": "height",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Exact height (alias: h). Overrides size."
          },
          {
            "name": "retina",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Double the requested dimensions."
          },
          {
            "name": "greyscale",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "fallback",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "404"
              ]
            },
            "description": "Return HTTP 404 on a miss instead of a generated lettermark."
          }
        ],
        "responses": {
          "200": {
            "description": "Unknown ticker: a lettermark of the symbol, short-cached. x-favi-result: lettermark:unknown-ticker.",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/avif": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the listing’s domain logo URL."
          },
          "400": {
            "description": "Not a ticker at all."
          },
          "404": {
            "description": "Only with fallback=404: unknown ticker. x-favi-result: miss:unknown-ticker."
          }
        }
      }
    }
  }
}