Logo.dev Flags API

openapi: 3.2.0
info:
  title: Logo.dev Flags 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: Flags
  description: Submit domains with incorrect or outdated brand data for review.
paths:
  /v2/flag:
    post:
      tags:
      - Flags
      summary: Flag domains for review
      description: Submits domains with incorrect or outdated brand data for review. Nothing changes on a brand until a reviewer acts, and flagging never creates a webhook subscription. Not billed. Needs the Pro plan or above.
      operationId: v2Flag
      x-mint:
        metadata:
          description: Submit domains with incorrect or outdated brand data for review.
          tag: Pro or Enterprise
        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: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2FlagInput'
            example:
              domains:
              - https://www.acme.com
              - example.com
              reason: incorrect_logo
      responses:
        '200':
          description: The domains were submitted for review.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/V2Flag'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                  object: flag
                  domains:
                  - acme.com
                  - example.com
                  reason: incorrect_logo
                  comment: null
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '400':
          description: 'The body is invalid: malformed JSON, no domains or more than 100, a value that is not a domain, or an unknown `reason`. Nothing is submitted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              examples:
                domain_count:
                  value:
                    error:
                      code: invalid_request
                      message: 'domains must name between 1 and 100 domains: bad format'
                      target: domains
                    docs_url: https://www.logo.dev/docs/platform/errors
                domain:
                  value:
                    error:
                      code: invalid_request
                      message: '"not a domain": bad format'
                      target: domains
                    docs_url: https://www.logo.dev/docs/platform/errors
                reason:
                  value:
                    error:
                      code: invalid_request
                      message: '"wrong_color" is not a reason: bad format'
                      target: reason
                    docs_url: https://www.logo.dev/docs/platform/errors
        '401':
          description: The secret key is missing, malformed, unknown, or disabled, or it is not attached to a Logo.dev account. A publishable key (`pk_`) is refused.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/V2AuthError'
                - $ref: '#/components/schemas/V2Error'
              examples:
                invalid_key:
                  value:
                    msg: invalid api token. make sure to use your secret key.
                    docs_url: https://www.logo.dev/docs/platform/api-keys
                no_account:
                  value:
                    error:
                      code: unauthorized
                      message: this api key is not attached to a logo.dev account. check the key, or contact support@logo.dev
                    docs_url: https://www.logo.dev/docs/platform/errors
        '403':
          description: Your plan is below Pro, the account is suspended, or personal keys are turned off because you belong to a team. The last two return a `msg` field, as an authentication error does.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/V2Error'
                - $ref: '#/components/schemas/V2AuthError'
              examples:
                plan:
                  value:
                    error:
                      code: forbidden
                      message: brand flagging requires the pro plan or above
                    docs_url: https://www.logo.dev/docs/platform/errors
                suspended:
                  value:
                    msg: account suspended. contact team@logo.dev for more information
                    docs_url: https://www.logo.dev/docs/platform/errors
        '429':
          description: Too many flag requests this minute. Flags have their own limit of 10 requests per minute per account. Wait for `RateLimit-Reset` seconds. Nothing is submitted.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/V2FlagRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/V2FlagRateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/V2FlagRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: rate_limited
                  message: rate limit reached. no more than 10 flag requests per minute per account.
                docs_url: https://www.logo.dev/docs/platform/rate-limits
        '500':
          description: Submitting the domains failed. Domains submitted before the failure stay submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to submit the domains
                docs_url: https://www.logo.dev/docs/platform/errors
components:
  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
    V2Flag:
      type: object
      properties:
        object:
          type: string
          const: flag
        domains:
          type: array
          items:
            type: string
          description: The normalized domains submitted for review, without duplicates, in the order you sent them.
        reason:
          type: string
          enum:
          - incorrect_logo
          - incorrect_brand
          - outdated_data
          - other
        comment:
          type:
          - string
          - 'null'
          description: The comment as submitted. `null` when you sent none.
      required:
      - object
      - domains
      - reason
      - comment
    V2FlagInput:
      type: object
      properties:
        domains:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: The domains to submit for review. Each is normalized the way domain lookups are, so `https://www.acme.com` becomes `acme.com`, and duplicates are removed. One invalid domain rejects the whole request.
        reason:
          type: string
          enum:
          - incorrect_logo
          - incorrect_brand
          - outdated_data
          - other
          description: Why the domains need review. Applies to every domain in the request.
        comment:
          type: string
          description: Details for the reviewers. Leading and trailing whitespace is trimmed, and text past 2,000 characters is cut off.
      required:
      - domains
      - reason
    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
    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
    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
  headers:
    V2FlagRateLimitReset:
      description: Seconds until the current flag window resets.
      schema:
        type: integer
    V2FlagRateLimitRemaining:
      description: Flag requests left in the current minute.
      schema:
        type: integer
    V2FlagRateLimitLimit:
      description: Flag requests allowed per minute for your account. Flags have their own pool, separate from lookups and search.
      schema:
        type: integer
  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.