Logo.dev Search API

openapi: 3.2.0
info:
  title: Logo.dev Search API
  description: 'Logo.dev serves brand assets from two hosts, each with its own key:


    - **Logo.dev CDN** (`img.logo.dev`) returns a logo image. Authenticate with a **publishable key** in the `token` query parameter. It is safe in client-side code.

    - **Logo.dev API** (`api.logo.dev`) returns JSON. Authenticate with a **secret key** in the `Authorization: Bearer` header. Call it only from your server.


    Get your keys from the dashboard.'
  version: 2.0.0
  contact:
    name: Logo.dev Support
    email: support@logo.dev
    url: https://docs.logo.dev
servers:
- url: https://api.logo.dev
  description: REST APIs (Brand Search, Brand Data)
tags:
- name: Search
  description: Find brands by name.
paths:
  /v2/search:
    get:
      tags:
      - Search
      summary: Search brands
      description: Finds brands by name and returns candidates with their domain and logo URL. `match` searches full names and aliases; `typeahead` completes a prefix as someone types. Costs API credits on every request, at the rate in API credits. Follow up with Look up a brand for the full profile.
      operationId: v2SearchBrands
      x-mint:
        metadata:
          description: Search brands by name, with match or typeahead ranking, and get each candidate's domain and logo URL.
          tag: 1 credit / 1,000 searches
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      parameters:
      - name: q
        in: query
        required: true
        description: The name to search for.
        schema:
          type: string
          examples:
          - sweetgreen
      - name: method
        in: query
        required: false
        description: '`match` for full names, `typeahead` for partial input.'
        schema:
          type: string
          enum:
          - match
          - typeahead
          default: match
      - name: limit
        in: query
        required: false
        description: Results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 25
          default: 10
      responses:
        '200':
          description: Matching brands, best first. An empty array when nothing matches.
          headers:
            Request-Id:
              $ref: '#/components/headers/V2RequestId'
            Credits-Charged:
              $ref: '#/components/headers/V2CreditsCharged'
            Credits-Remaining:
              $ref: '#/components/headers/V2CreditsRemaining'
            RateLimit-Limit:
              $ref: '#/components/headers/V2SearchRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/V2SearchRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/V2SearchRateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/V2SearchResult'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                - object: search_result
                  name: Sweetgreen
                  domain: sweetgreen.com
                  logo_url: https://img.logo.dev/sweetgreen.com?token=LOGO_DEV_PUBLISHABLE_KEY
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '400':
          description: '`q` is missing, or `method` or `limit` is invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: invalid_request
                  message: q is required
                  target: q
                docs_url: https://www.logo.dev/docs/platform/errors
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '402':
          $ref: '#/components/responses/V2SearchPaymentRequired'
        '429':
          $ref: '#/components/responses/V2SearchRateLimited'
        '500':
          description: Search failed. Retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to search
                docs_url: https://www.logo.dev/docs/platform/errors
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/V2SearchRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/V2SearchRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/V2SearchRateLimitReset'
components:
  headers:
    V2CreditsRemaining:
      description: Your remaining API credit balance. Omitted when no balance is available.
      schema:
        type: string
        examples:
        - '18966.99'
    V2SearchRateLimitReset:
      description: Seconds until the current search window resets.
      schema:
        type: integer
    V2SearchRateLimitLimit:
      description: Search requests allowed per minute for your account. Search has its own pool, separate from brand lookups.
      schema:
        type: integer
    V2RequestId:
      description: Unique id for this request. Include it when you contact support.
      schema:
        type: string
    V2SearchRateLimitRemaining:
      description: Search requests left in the current minute.
      schema:
        type: integer
    V2CreditsCharged:
      description: '`1` when this request was billed, `0` when it was not.'
      schema:
        type: integer
        enum:
        - 0
        - 1
  schemas:
    V2Resolution:
      type: object
      description: How the request identified the brand.
      properties:
        type:
          type: string
          enum:
          - domain
          - ticker
          - isin
          - crypto
          - name
          - brand_id
          description: Which identifier the request used.
        value:
          type: string
          description: 'The identifier after normalization: the registrable domain, an upper-cased ticker, and so on.'
        method:
          type: string
          enum:
          - direct
          - domain
          - security
          - crypto
          - search
          - ''
          description: How the identifier reached the brand. `direct` is a brand id or a domain that is its own brand; `domain` went through an alias or redirect; `security` is a ticker or ISIN; `crypto` is a crypto token symbol; `search` is a name lookup. Empty on a cached miss.
        context:
          type: object
          description: Reserved for brands involved in a merchant lookup. Always `{}` today.
      required:
      - type
      - value
      - method
      - context
    V2Metadata:
      type: object
      properties:
        request_id:
          type: string
          description: Unique id for this request. Also sent as the `Request-Id` header.
          examples:
          - request_01k6z8m2a4b5c6d7e8f9g0h1j2
        resolution:
          allOf:
          - $ref: '#/components/schemas/V2Resolution'
          description: Brand and image lookups only.
        pending:
          allOf:
          - $ref: '#/components/schemas/V2Pending'
          description: '`202` responses only.'
        subscription:
          type: object
          description: 'Present when a brand lookup (`GET /v2/brands` or `GET /v2/brands/{id}`) ran the automatic subscribe: webhooks are on for the account, and `nosubscribe` is not `true`. See [automatic subscriptions](/brand/introduction#automatic-subscriptions).'
          properties:
            status:
              type: string
              enum:
              - subscribed
              - quota_exceeded
              description: '`subscribed`: the account is subscribed to the brand. `quota_exceeded`: the account is at its plan''s subscription limit, so the brand was not subscribed. The lookup is answered and billed either way.'
            message:
              type: string
              description: Why the subscribe was refused. Only with `quota_exceeded`.
          required:
          - status
      required:
      - request_id
    V2AuthError:
      type: object
      description: Returned when the secret key is missing, malformed, unknown, or disabled, before the request reaches the v2 route.
      properties:
        msg:
          type: string
        docs_url:
          type: string
          format: uri
      required:
      - msg
    V2Pending:
      type: object
      description: Present only on a `202`. Tells you when to retry.
      properties:
        reason:
          type: string
          enum:
          - indexing
          - resolving
          description: '`indexing` is a brand''s first crawl; `resolving` means the identifier is still being matched to a brand.'
        message:
          type: string
        retry_after_seconds:
          type: integer
          description: Wait this long before retrying. Matches the `Retry-After` header.
          examples:
          - 30
        expires_in_seconds:
          type: integer
          description: Stop polling after this long.
          examples:
          - 300
        webhook:
          type: boolean
          description: Whether a `brand.indexed` webhook event carrying this request's `request_id` will be sent when the lookup settles.
        doc_url:
          type: string
          format: uri
      required:
      - reason
      - message
      - retry_after_seconds
      - expires_in_seconds
      - webhook
      - doc_url
    V2SearchResult:
      type: object
      properties:
        object:
          type: string
          const: search_result
        name:
          type: string
        domain:
          type: string
        logo_url:
          type: string
          format: uri
          description: Logo URL signed with your account's publishable key.
      required:
      - object
      - name
      - domain
      - logo_url
    V2Error:
      type: object
      description: Error envelope for v2 routes.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - unauthorized
              - forbidden
              - resource_missing
              - insufficient_credits
              - rate_limited
              - limit_exceeded
              - internal
            message:
              type: string
            target:
              type: string
              description: The parameter at fault, when there is exactly one.
          required:
          - code
          - message
        docs_url:
          type: string
          format: uri
          description: Documentation for this class of error.
      required:
      - error
  responses:
    V2SearchPaymentRequired:
      description: Your account is out of API credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              code: insufficient_credits
              message: out of credits for the brand API. purchase credits at https://www.logo.dev/dashboard
            docs_url: https://www.logo.dev/docs/platform/errors
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/V2SearchRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/V2SearchRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/V2SearchRateLimitReset'
    V2SearchRateLimited:
      description: Too many searches this minute. Search has its own per-minute limit, separate from lookups. Wait for `RateLimit-Reset` seconds. Not billed. See [search rate limit](/platform/rate-limits#search-rate-limit).
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/V2SearchRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/V2SearchRateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/V2SearchRateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              code: rate_limited
              message: rate limit reached. no more than {limit} search requests per minute per account.
            docs_url: https://www.logo.dev/docs/platform/rate-limits
    V2Unauthorized:
      description: The secret key is missing, malformed, unknown, or disabled. A publishable key (`pk_`) is refused.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/V2AuthError'
            - $ref: '#/components/schemas/V2Error'
          example:
            msg: invalid api token. make sure to use your secret key.
            docs_url: https://www.logo.dev/docs/platform/api-keys
  securitySchemes:
    publishableKey:
      type: apiKey
      in: query
      name: token
      description: Your publishable key (`pk_`). Safe in client-side code. Works only with the Logo.dev CDN.
    secretKey:
      type: http
      scheme: bearer
      description: Your secret key (`sk_`), as `Bearer sk_...`. Call the Logo.dev API only from your server.
    transactionBetaKey:
      type: http
      scheme: bearer
      bearerFormat: tx_beta_…
      description: Transaction-only beta key, issued with your beta access and always visible in the Transaction Playground. Existing Logo.dev secret keys do not authenticate this beta.