> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydrafetch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search the news

> Find recent news articles about a query, newest first, each with its outlet and publish time. Costs 1 credit; a search that finds nothing is free. Set `scrapeResults` to true to also read each article as clean data, at 1 additional credit per article read.



## OpenAPI

````yaml https://api.hydrafetch.com/openapi.json post /v1/web/news
openapi: 3.0.0
info:
  title: Hydrafetch API
  description: >-
    Hydrafetch is a web data API for developers and AI agents. Give it a URL or
    a query and it returns clean markdown and structured data: scrape, crawl,
    map, search, news, jobs, extraction, brand data and screenshots, over one
    API and an MCP server. A page read costs one credit and a failed page costs
    nothing.


    Point us at a whole site and get every page. Ask a question and get answers
    with per-field

    confidence and the passage each value came from. You describe the outcome
    you want — the

    pipeline decides how to get it.


    ## Authentication


    Every request is authenticated with your API key in the `X-API-Key` header.
    Keys are scoped to a

    workspace and carry its credit balance.


    ## Credits


    Calls are billed in credits and charged only on success. A standard scrape
    is one credit; richer

    formats and the extraction tier cost more. Each response reports what it
    consumed.


    ## Conventions


    All timestamps are UTC ISO 8601. Long-running jobs (crawl, batch) return a
    job id you poll, or a

    webhook you register.


    ## Errors


    Every failure returns the same shape, whatever the status:


    ```json

    { "success": false, "error": { "code": "INSUFFICIENT_CREDITS", "message":
    "Insufficient credits" },
      "meta": { "requestId": "019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c" } }
    ```


    Branch on `error.code`, which is stable. `error.message` is written for a
    person and may be

    reworded without notice. Validation failures add `error.details`. Quote
    `meta.requestId` when

    asking us about a specific failure. Every operation documents the codes it
    can return.


    ## Rate limits


    Limits are per workspace, not per key, over a 60 second window, and the
    ceiling comes from your

    plan. Every response carries the IETF RateLimit header fields so you can
    self-throttle rather

    than discovering the limit by hitting it:


    ```http

    RateLimit-Policy: "workspace";q=600;w=60

    RateLimit: "workspace";r=599;t=42

    ```


    `q` is the quota, `w` the window in seconds, `r` the requests remaining and
    `t` the seconds until

    the window resets. A 429 also carries `Retry-After` in seconds; wait that
    long rather than

    retrying immediately. The older `X-RateLimit-Limit`, `X-RateLimit-Remaining`
    and

    `X-RateLimit-Reset` headers are still sent and mean the same thing.


    ## Versioning and deprecation


    The version is in the path: every endpoint on this API lives under `/v1/`.
    Within a version we

    only make additive changes — new endpoints, new optional parameters, new
    fields in a response.

    Adding a field to a response is not a breaking change, so parse defensively
    and ignore what you

    do not recognise.


    Anything that would break an existing integration ships under a new version
    path instead. When an

    endpoint or a version is retired, the responses say so before it stops
    working:


    ```http

    Deprecation: @1780272000

    Sunset: Sat, 01 May 2027 00:00:00 GMT

    Link: <https://docs.hydrafetch.com/changelog>; rel="deprecation"

    ```


    `Deprecation` (RFC 9745) marks when the endpoint became deprecated, `Sunset`
    (RFC 8594) when it

    stops responding, and the `deprecation` link relation points at what to move
    to. Nothing on this

    API is deprecated today, so you will not see these headers yet. Watch for
    them rather than for an

    announcement: the headers are the notice, and the linked changelog carries
    what to move to.
  version: '1.0'
  contact:
    name: Hydrafetch
    url: https://hydrafetch.com
    email: support@hydrafetch.com
servers:
  - url: https://api.hydrafetch.com
    description: Production
security:
  - apiKey: []
tags:
  - name: Scrape
    description: >-
      Turn one URL into clean, LLM-ready content. Ask for Markdown, HTML, links,
      or the page’s own structured data, and poll a job id when a fetch runs
      long.
  - name: Crawl & batch
    description: >-
      Whole sites rather than single pages. Map every URL, crawl with depth and
      path rules, batch a list you already have, and read the webhook deliveries
      for either.
  - name: Search
    description: >-
      Search the web and get the ranked results back already scraped, so an
      agent has content to cite rather than links to fetch.
  - name: Extract
    description: >-
      Pull schema-shaped JSON out of one or many pages, with optional per-field
      confidence and the source passage behind each value.
  - name: Brand
    description: >-
      Resolve a domain into the company ready to render: logos for light and
      dark, the palette ranked by how the site uses it, fonts, socials, and the
      design system behind them.
  - name: Media
    description: >-
      Images and screenshots from a page, with source and alt text, or a
      rendered capture of the page as it appears.
paths:
  /v1/web/news:
    post:
      tags:
        - News
      summary: Search the news
      description: >-
        Find recent news articles about a query, newest first, each with its
        outlet and publish time. Costs 1 credit; a search that finds nothing is
        free. Set `scrapeResults` to true to also read each article as clean
        data, at 1 additional credit per article read.
      operationId: newsRun
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Any unique string up to 255 visible characters. Send the same key
            when you retry a request: for 12 hours a repeat returns the first
            answer again, with an Idempotent-Replayed: true header, without
            doing the work or charging a second time. A repeat that arrives
            while the first is still running gets 409 IDEMPOTENCY_IN_PROGRESS;
            the same key with a different body gets 409 IDEMPOTENCY_KEY_REUSED.
          schema:
            type: string
            maxLength: 255
            example: 3f2b8c1e-retry-safe-key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsRequestDto'
      responses:
        '200':
          description: Matching articles, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponseDto'
        '202':
          description: Still running; poll /v1/web/jobs/{id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallAcceptedDto'
        '400':
          description: The request body or query failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: url must be a valid URL
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '401':
          description: >-
            The X-API-Key header is missing, malformed, or names a key that no
            longer exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: >-
                    Missing X-API-Key header. Agents:
                    https://hydrafetch.com/auth.md
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '402':
          description: >-
            The workspace has no credits left for this request. Nothing was
            charged and nothing was fetched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: INSUFFICIENT_CREDITS
                  message: Insufficient credits
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '403':
          description: The key is valid but the workspace may not make this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: WORKSPACE_BANNED
                  message: >-
                    This workspace has been suspended and cannot make API
                    requests.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '404':
          description: No such job, or the id belongs to another workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Job not found
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '409':
          description: >-
            The Idempotency-Key on this request is still running from an earlier
            attempt (IDEMPOTENCY_IN_PROGRESS: wait Retry-After seconds and send
            it again to get the saved answer), or was already used with a
            different request body (IDEMPOTENCY_KEY_REUSED: use a new key).
            Nothing was charged.
          headers:
            Retry-After:
              description: Seconds to wait before sending the same request again.
              schema:
                type: integer
                example: 2
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: IDEMPOTENCY_IN_PROGRESS
                  message: A request with this Idempotency-Key is still running.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '422':
          description: >-
            The target site did not respond, or we could not read that page.
            This is a fact about that URL rather than a fault on our side, and
            retrying it will not change the answer. When
            details.retryAfterSeconds is present, asking again before then
            returns this same answer. Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: UPSTREAM_UNREACHABLE
                  message: The origin did not respond to any attempt we made.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '429':
          description: >-
            The workspace exceeded its per-minute request limit. Read the
            RateLimit headers, or Retry-After on this response, and retry after
            the window resets.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Prefer this over a fixed
                backoff.
              schema:
                type: integer
                example: 17
            RateLimit:
              description: Requests remaining (r) and seconds until the window resets (t).
              schema:
                type: string
                example: '"workspace";r=0;t=17'
            RateLimit-Policy:
              description: >-
                The quota (q) for your plan and the window it applies over (w),
                in seconds.
              schema:
                type: string
                example: '"workspace";q=600;w=60'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: TOO_MANY_REQUESTS
                  message: Rate limit exceeded for this workspace and plan.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '500':
          description: Unexpected server error. Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: Internal server error
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '503':
          description: >-
            A dependency needed for the requested formats is unavailable. Safe
            to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: SERVICE_UNAVAILABLE
                  message: The summary and json formats are not available.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
components:
  schemas:
    NewsRequestDto:
      type: object
      properties:
        query:
          type: string
          maxLength: 500
          example: startup raises series A
          description: What to find news about.
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          example: 10
          description: How many articles to return, newest first.
        timeRange:
          type: string
          enum:
            - hour
            - day
            - week
            - month
          default: week
          example: week
          description: Only articles published within this window before now.
        maxAge:
          type: integer
          minimum: 0
          example: 0
          description: >-
            Accept a recent answer to the same search no older than this many
            milliseconds. Leave it out to accept answers up to 5 minutes old for
            `hour`, 15 for `day` and 30 for `week` or `month`. `0` always
            searches fresh.
        country:
          type: string
          example: us
          description: ISO 3166 alpha-2 country code to lean results toward that edition.
        includeDomains:
          maxItems: 15
          example:
            - techcrunch.com
          description: Only return articles from these sites.
          type: array
          items:
            type: string
        excludeDomains:
          maxItems: 15
          example:
            - prnewswire.com
          description: Drop articles from these sites.
          type: array
          items:
            type: string
        scrapeResults:
          type: boolean
          example: false
          description: >-
            When true, each article also comes back with its page read and
            returned as clean data, at 1 additional credit per article read.
        scrapeOptions:
          $ref: '#/components/schemas/ScrapeOptionsDto'
      required:
        - query
    NewsResponseDto:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/NewsResultDto'
      required:
        - data
    CallAcceptedDto:
      type: object
      properties:
        jobId:
          type: string
          example: 019f3c09-6fae-740f-9257-10c2b6af7f43
        status:
          type: string
          enum:
            - running
          example: running
        poll:
          type: string
          example: /v1/web/jobs/019f3c09-6fae-740f-9257-10c2b6af7f43
          description: Poll this path until the status is completed or failed.
      required:
        - jobId
        - status
        - poll
    WebError:
      type: object
      required:
        - success
        - error
        - meta
      description: >-
        Every failure on this API returns this shape, whatever the status.
        Successful responses never carry it.
      properties:
        success:
          type: boolean
          enum:
            - false
          example: false
        error:
          $ref: '#/components/schemas/WebErrorBody'
        meta:
          $ref: '#/components/schemas/WebErrorMeta'
    ScrapeOptionsDto:
      type: object
      properties:
        formats:
          type: array
          example:
            - markdown
          description: What to return per page. Omit for Markdown only.
          items:
            type: string
            enum:
              - markdown
              - html
              - rawHtml
              - links
              - structured
        onlyMainContent:
          type: boolean
          description: Return only the main content, dropping boilerplate. Default true.
        includeTags:
          maxItems: 50
          description: CSS selectors to keep.
          type: array
          items:
            type: string
        excludeTags:
          maxItems: 50
          description: CSS selectors to strip before extraction.
          type: array
          items:
            type: string
        removeBase64Images:
          type: boolean
          description: Strip inline base64 images. Default true.
        blockAds:
          type: boolean
          description: Remove ads and tracking elements. Default true.
        dismissCookies:
          type: boolean
          description: >-
            Remove cookie and consent banners. Default true. Set false to keep
            them; a banner the site adds with scripts after load is kept only
            when the page is rendered.
        dismissPopups:
          type: boolean
          description: >-
            Close newsletter and promotion popups when the page is rendered.
            Default true. Set false to keep them.
        render:
          type: boolean
          description: >-
            Always read the page in a browser, as a visitor sees it once its
            scripts have run. Default false: the page is read in a browser only
            when its HTML is not enough. Combine with dismissCookies and
            dismissPopups set to false to keep what scripts add after load.
        includeLinks:
          type: boolean
          description: >-
            Keep inline links in the markdown. By default links are kept
            wherever the page text carries them. Set true to keep them on every
            page, or false for the densest prose.
        waitFor:
          type: integer
          minimum: 0
          maximum: 30000
          description: Extra milliseconds to let the page settle before capture.
        waitForSelector:
          type: string
          maxLength: 500
          example: .price
          description: >-
            A CSS selector to wait for before capture. The page is rendered in a
            browser and read once an element matching it exists, or when the
            time budget runs out, in which case the result says the element
            never appeared.
        mobile:
          type: boolean
          description: >-
            Render the page as a phone would see it: a phone-sized screen, touch
            and a mobile browser identity. Use it for sites that serve different
            content to phones.
        timeout:
          type: integer
          minimum: 1000
          maximum: 100000
          description: Per-page time budget, in milliseconds.
        location:
          $ref: '#/components/schemas/LocationDto'
        headers:
          type: object
          additionalProperties:
            type: string
          description: Extra request headers to send when fetching each page.
        preferStructure:
          type: boolean
          description: Preserve document structure over prose density. Default off.
        maxAge:
          type: integer
          minimum: 0
          maximum: 604800000
          description: Serve a page from cache if younger than this many milliseconds.
    NewsResultDto:
      type: object
      properties:
        query:
          type: string
          example: startup raises series A
          description: The query you searched.
        status:
          type: string
          enum:
            - ok
            - no_results
          example: ok
          description: >-
            `ok` when articles were found, `no_results` when none matched in the
            window. If news cannot be searched at all, the request fails with
            503 rather than returning an empty list.
        results:
          description: Articles, newest first.
          type: array
          items:
            $ref: '#/components/schemas/NewsResultItemDto'
      required:
        - query
        - status
        - results
    WebErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - VALIDATION_ERROR
            - INVALID_INPUT
            - UNAUTHORIZED
            - INSUFFICIENT_CREDITS
            - FORBIDDEN
            - WORKSPACE_BANNED
            - NOT_FOUND
            - IDEMPOTENCY_IN_PROGRESS
            - IDEMPOTENCY_KEY_REUSED
            - TOO_MANY_REQUESTS
            - UPSTREAM_UNREACHABLE
            - SERVICE_UNAVAILABLE
            - INTERNAL_SERVER_ERROR
          description: >-
            Stable, machine-readable reason. Branch on this rather than on the
            message, which may be reworded.
          example: INSUFFICIENT_CREDITS
        message:
          type: string
          description: Human-readable explanation. Safe to show a user, not to parse.
          example: Insufficient credits
        details:
          type: object
          additionalProperties: true
          description: Optional machine-readable context, present on validation failures.
    WebErrorMeta:
      type: object
      properties:
        requestId:
          type: string
          description: Quote this when contacting support about a specific failure.
          example: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
    LocationDto:
      type: object
      properties:
        country:
          type: string
          example: us
          description: >-
            Two-letter country to read the page from: `us` or `de`. Any other
            country is refused with a 400 that lists the supported codes.
        languages:
          example:
            - en-US
            - en
          description: Preferred content languages, most-preferred first.
          type: array
          items:
            type: string
    NewsResultItemDto:
      type: object
      properties:
        title:
          type: string
          example: Acme raises $45M in Series A round
          description: The headline.
        url:
          type: string
          example: https://example.com/news/acme-series-a
          description: The article's address on the publisher's own site.
        source:
          type: string
          nullable: true
          example: Example News
          description: The outlet that published it.
        publishedAt:
          type: string
          example: '2026-11-03T09:12:00.000Z'
          description: >-
            When it was published. Exact when the listing gives a time,
            otherwise worked out from its stated age, such as 2 days ago.
        snippet:
          type: string
          nullable: true
          example: The startup raised $45 million to expand into Europe.
          description: A short summary of the article.
        data:
          nullable: true
          description: >-
            The article read as clean data, or null when `scrapeResults` is off
            or the page could not be read.
          type: object
          allOf:
            - $ref: '#/components/schemas/WebScrapeDataDto'
      required:
        - title
        - url
        - source
        - publishedAt
        - snippet
        - data
    WebScrapeDataDto:
      type: object
      properties:
        url:
          type: string
          example: https://example.com
          description: The URL you requested.
        finalUrl:
          type: string
          example: https://example.com/
          description: The final URL after any redirects.
        redirected:
          type: boolean
          example: false
          description: >-
            Whether the origin redirected: true when `finalUrl` differs from the
            URL you requested. Explicit so a page with no redirect is
            distinguishable from one whose redirect was not tracked.
        status:
          type: integer
          example: 200
          description: HTTP status of the fetched page.
        cached:
          type: boolean
          example: false
          description: Whether this result was served from cache.
        warning:
          type: string
          description: Set when the page was returned with a caveat (e.g. partial content).
        metadata:
          $ref: '#/components/schemas/WebScrapeMetadataDto'
        usage:
          $ref: '#/components/schemas/WebUsageDto'
        quality:
          description: Per-page extraction quality signals.
          allOf:
            - $ref: '#/components/schemas/WebQualityDto'
        markdown:
          type: string
          description: >-
            Clean Markdown of the main content. Returned when `markdown` is
            requested.
        html:
          type: string
          description: Cleaned main-content HTML. Returned when `html` is requested.
        rawHtml:
          type: string
          description: The unmodified page HTML. Returned when `rawHtml` is requested.
        links:
          description: Returned when `links` is requested.
          allOf:
            - $ref: '#/components/schemas/WebLinksDto'
        structured:
          description: Returned when `structured` is requested.
          allOf:
            - $ref: '#/components/schemas/WebStructuredDataDto'
        summary:
          type: string
          description: >-
            A concise factual summary. Returned when `summary` is requested
            (LLM-backed).
        json:
          type: object
          additionalProperties: true
          description: Schema-shaped JSON. Returned when `json` is requested (LLM-backed).
        brand:
          description: >-
            The site's brand: logos, colours and fonts. Returned when `brand` is
            requested.
          allOf:
            - $ref: '#/components/schemas/WebBrandDataDto'
      required:
        - url
        - finalUrl
        - redirected
        - status
        - cached
        - metadata
    WebScrapeMetadataDto:
      type: object
      properties:
        title:
          type: string
          nullable: true
          example: Example Domain
          description: The page title.
        structure:
          type: string
          enum:
            - markdown
            - plain
          example: markdown
          description: >-
            Whether the content carries markdown structure (headings, lists,
            emphasis) or is plain prose. `plain` is not an error — the default
            extractor optimises for capturing every word and wins on listing and
            forum pages. If you need the structure, re-request with
            `preferStructure: true`.
        pageType:
          type: string
          example: article
          description: Coarse page classification (e.g. article, listing, forum, docs).
        wordCount:
          type: integer
          example: 214
          description: Word count of the extracted main content.
        description:
          type: string
          nullable: true
          example: A short summary of the page, as published by the page itself.
          description: The page's own description (meta description / og:description).
        language:
          type: string
          nullable: true
          example: en
          description: The language the page declares.
        author:
          type: string
          nullable: true
          example: Jane Doe
          description: The declared author.
        siteName:
          type: string
          nullable: true
          example: Example Blog
          description: The declared site name.
        publishedTime:
          type: string
          nullable: true
          example: '2026-01-05'
          description: When the page says it was published (ISO 8601).
        modifiedTime:
          type: string
          nullable: true
          example: '2026-02-11'
          description: When the page says it was last updated (ISO 8601).
        image:
          type: string
          nullable: true
          example: https://example.com/cover.png
          description: The page's lead image (og:image).
      required:
        - title
        - structure
        - pageType
        - wordCount
        - description
        - language
        - author
        - siteName
        - publishedTime
        - modifiedTime
        - image
    WebUsageDto:
      type: object
      properties:
        creditsUsed:
          type: integer
          example: 1
          description: Credits this call consumed. Charged only on success.
        creditsRemaining:
          type: integer
          example: 4999
          description: Credits left in your workspace's balance after this call.
        freshness:
          type: string
          enum:
            - cache
            - fresh
          example: fresh
          description: Whether the result was served from cache or freshly fetched.
      required:
        - creditsUsed
        - creditsRemaining
        - freshness
    WebQualityDto:
      type: object
      properties:
        confidence:
          type: number
          example: 0.94
          minimum: 0
          maximum: 1
          description: >-
            How trustworthy the extraction is, from 0 to 1. High when
            independent checks corroborate substantial content; near zero when
            the page yielded almost nothing.
        complete:
          type: boolean
          example: true
          description: >-
            Whether the result captured the bulk of the content available on the
            page. False when the result looks thin or truncated.
        blocked:
          type: boolean
          example: false
          description: Whether the page appeared to be behind a challenge or bot wall.
      required:
        - confidence
        - complete
        - blocked
    WebLinksDto:
      type: object
      properties:
        internal:
          description: Links pointing to the same site.
          type: array
          items:
            type: string
        external:
          description: Links pointing to other sites.
          type: array
          items:
            type: string
      required:
        - internal
        - external
    WebStructuredDataDto:
      type: object
      properties:
        entities:
          description: >-
            The page's own structured data, normalised into one deduplicated
            list of typed entities.
          type: array
          items:
            $ref: '#/components/schemas/WebStructuredEntityDto'
        jsonLd:
          description: Raw JSON-LD blocks, as found on the page.
          type: array
          items:
            type: object
        microdata:
          description: Raw microdata items.
          type: array
          items:
            type: object
        opengraph:
          description: Raw OpenGraph/Twitter-card tags.
          type: array
          items:
            type: object
        appState:
          description: Names of embedded framework app-state blocks detected on the page.
          type: array
          items:
            type: string
      required:
        - entities
        - jsonLd
        - microdata
        - opengraph
        - appState
    WebBrandDataDto:
      type: object
      properties:
        domain:
          type: string
          example: stripe.com
          description: The canonical domain for this company.
        queriedDomain:
          type: string
          example: stripe.co.uk
          description: Only when you asked for a different domain that resolved here.
        aliases:
          description: Only when this brand is known by more than its canonical domain.
          type: array
          items:
            type: string
        name:
          type: string
          nullable: true
          example: Stripe
        description:
          type: string
          nullable: true
          example: >-
            Stripe powers online and in-person payment processing and financial
            solutions for businesses of all sizes.
        tagline:
          type: string
          nullable: true
          example: Financial infrastructure to grow your revenue.
        naics:
          description: >-
            Industry, as a real NAICS code rather than a phrase nobody can group
            on.
          allOf:
            - $ref: '#/components/schemas/BrandNaicsDto'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/BrandAssetDto'
        colors:
          type: array
          items:
            $ref: '#/components/schemas/BrandColorDto'
        fonts:
          type: array
          items:
            $ref: '#/components/schemas/BrandFontDto'
        socials:
          type: array
          items:
            $ref: '#/components/schemas/BrandSocialDto'
        links:
          $ref: '#/components/schemas/BrandLinksDto'
        email:
          type: string
          example: support@stripe.com
        legalName:
          type: string
          example: Stripe, Inc.
        metaDescription:
          type: string
          example: >-
            Stripe powers online and in-person payment processing for businesses
            of all sizes.
          description: The site's own meta description, word for word.
        phone:
          type: string
          example: +1 888 926 2289
          description: A phone number the site publishes for the company.
        address:
          description: The address the site publishes for the company.
          allOf:
            - $ref: '#/components/schemas/BrandAddressDto'
        foundedYear:
          type: number
          example: 2010
          description: The year the site says the company was founded.
        sources:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BrandFieldProvenanceDto'
          description: >-
            Per-field provenance, keyed by field name. Lets you tell "their
            markup says this" from "a model guessed this".
        resolvedAt:
          type: string
          nullable: true
          example: '2026-08-22T10:14:03.000Z'
      required:
        - domain
        - name
        - description
        - tagline
        - assets
        - colors
        - fonts
        - socials
        - links
        - sources
        - resolvedAt
    WebStructuredEntityDto:
      type: object
      properties:
        type:
          type: string
          example: Product
          description: The schema.org type of the entity.
        source:
          type: string
          enum:
            - json-ld
            - microdata
            - opengraph
          description: Which structured-data syntax the entity came from.
        properties:
          type: object
          additionalProperties: true
          description: The entity's properties, as published.
      required:
        - type
        - source
        - properties
    BrandNaicsDto:
      type: object
      properties:
        code:
          type: string
          example: '5223'
        title:
          type: string
          example: Activities Related to Credit Intermediation
        level:
          type: string
          enum:
            - sector
            - industry_group
            - national_industry
          example: industry_group
          description: >-
            How specific the answer is. `industry_group` is the 4-digit level,
            `national_industry` the 6-digit one.
        sector:
          $ref: '#/components/schemas/BrandNaicsSectorDto'
        confidence:
          type: number
          example: 0.8
          minimum: 0
          maximum: 1
          description: >-
            How much evidence the classification found, not a model's
            self-report.
      required:
        - code
        - title
        - level
        - sector
        - confidence
    BrandAssetDto:
      type: object
      properties:
        kind:
          type: string
          enum:
            - wordmark
            - symbol
            - favicon
            - backdrop
          example: symbol
          description: What kind of mark this is.
        variant:
          type: string
          enum:
            - light
            - dark
            - mono
          example: light
          description: >-
            Which background the asset is legible on. `mono` is a single-colour
            mark that works on both.
        url:
          type: string
          example: https://media.hydrafetch.com/brand/a0/a07c2695173dde0a1ffa.svg
          description: Public and immutable, so it can be embedded anywhere.
        format:
          type: string
          example: svg
        resolution:
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/BrandResolutionDto'
        colors:
          description: >-
            The colours in the asset itself. A logo's own palette is the
            brand's, by definition.
          type: array
          items:
            $ref: '#/components/schemas/BrandColorDto'
        blurhash:
          type: string
          nullable: true
          example: LmGk_aoh4sWHohWEWDt506WD?Sod
          description: >-
            Tiny placeholder hash, so a client can render something before the
            image lands.
      required:
        - kind
        - variant
        - url
        - format
        - resolution
        - colors
        - blurhash
    BrandColorDto:
      type: object
      properties:
        hex:
          type: string
          example: '#533afd'
        name:
          type: string
          example: Indigo
          description: >-
            Nearest CSS colour name, so a swatch reads as something and not only
            as six digits.
        weight:
          type: number
          example: 0.42
          description: >-
            How much the site itself uses it — the ranking that makes this the
            brand's colour.
        role:
          type: string
          enum:
            - primary
            - accent
            - background
            - text
          example: primary
      required:
        - hex
        - weight
    BrandFontDto:
      type: object
      properties:
        family:
          type: string
          example: Sohne
        weight:
          type: number
          description: How much of the site's type this face sets, 1 for the most-used one.
          example: 1
        role:
          type: string
          description: Absent when the page does not say which the face is.
          enum:
            - heading
            - body
          example: body
      required:
        - family
        - weight
    BrandSocialDto:
      type: object
      properties:
        platform:
          type: string
          example: x
        url:
          type: string
          example: https://x.com/stripe
        handle:
          type: string
          example: stripe
          description: The account name, without the `@`.
      required:
        - platform
        - url
    BrandLinksDto:
      type: object
      properties:
        pricing:
          type: string
          example: https://stripe.com/pricing
        blog:
          type: string
          example: https://stripe.com/blog
        careers:
          type: string
          example: https://stripe.com/jobs
        contact:
          type: string
          example: https://stripe.com/contact
        privacy:
          type: string
          example: https://stripe.com/privacy
        terms:
          type: string
          example: https://stripe.com/legal
        docs:
          type: string
          example: https://docs.stripe.com
    BrandAddressDto:
      type: object
      properties:
        street:
          type: string
          nullable: true
          example: 354 Oyster Point Blvd
        city:
          type: string
          nullable: true
          example: South San Francisco
        region:
          type: string
          nullable: true
          example: CA
        postalCode:
          type: string
          nullable: true
          example: '94080'
        country:
          type: string
          nullable: true
          example: US
      required:
        - street
        - city
        - region
        - postalCode
        - country
    BrandFieldProvenanceDto:
      type: object
      properties:
        source:
          type: string
          enum:
            - declared
            - harvested
            - inferred
            - external
          example: declared
          description: >-
            `declared` the site said it in its own markup. `harvested` we
            processed an asset or read its CSS. `inferred` we worked it out
            rather than read it, such as a name taken from the domain.
            `external` an enrichment source rather than the site.
        confidence:
          type: number
          example: 0.9
          minimum: 0
          maximum: 1
      required:
        - source
    BrandNaicsSectorDto:
      type: object
      properties:
        code:
          type: string
          example: '52'
        title:
          type: string
          example: Finance and Insurance
      required:
        - code
        - title
    BrandResolutionDto:
      type: object
      properties:
        width:
          type: integer
          example: 180
        height:
          type: integer
          example: 180
        aspectRatio:
          type: number
          example: 1
          description: Width over height — what a caller reserves layout space with.
      required:
        - width
        - height
        - aspectRatio
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.