Responses

Company and search responses

/v1/companies/{identifier} returns a company object directly, with no data wrapper. /v1/search returns { "query": "Apple", "results": [...] }, where each result is a full company object. Unknown company lookups return 404; unmatched searches return 200 with an empty array.

Example of selected company fields (abridged, not the complete response):

{
  "id": "apple",
  "name": "Apple",
  "tickers": [{ "ticker": "AAPL", "symbol": "AAPL" }],
  "domain": "apple.com"
}

Optional descriptive fields can be null; arrays can be empty. Do not assume every company has a ticker, domain, description, or color. See the company schema.

Image responses

Successful logo requests return image/svg+xml or image/png. Normal image responses include X-Brandmarks-Company, X-Brandmarks-Variant, and X-Brandmarks-Theme. Monograms use X-Brandmarks-Fallback instead. Errors return JSON, even from the image endpoint.

Image and monogram responses include an ETag. Conditional GET and HEAD requests return 304 Not Modified when If-None-Match matches. Composed black and brand SVGs use validators derived from the final representation; untransformed files use the stored asset validator. JSON responses use Cache-Control: no-store and do not currently issue ETags. HEAD works on image, company, and search routes and returns the same status and headers without a body.

Error envelope

{"error":{"code":"not_found","message":"No company found for the requested identifier."}}

Branch on HTTP status and error.code, not exact message text. Error reference.