serpresult-com API keys API

openapi: 3.2.0
info:
  title: SerpResult API keys API
  version: 1.0.0
  summary: Search engine results as JSON.
  description: 'SerpResult returns the organic results of a web search as JSON. Two search

    endpoints, both synchronous: `GET /v1/query` runs one search and

    `POST /v1/bulk` runs up to 50 in one request. Everything else on this

    surface is the dashboard''s reporting and credential management. ## Authentication


    Public API calls send a secret key in the `Authorization` header:


    ```

    Authorization: Bearer sk_live_…

    ```


    Keys are minted in the dashboard (or through `POST /v1/api-keys` with a

    session cookie). `sk_live_` keys are for production traffic, `sk_test_` keys

    carry a lower rate limit. The dashboard''s session cookie is accepted on the

    same endpoints. Routes marked **session only** (usage, history, key

    management) refuse a bearer key: a key that could mint another key would

    make revoking the first one meaningless. Two more principals exist and are described as security schemes below:

    the marketing site''s keyless demo (`X-Demo-Origin`) and RapidAPI''s proxy

    (`X-RapidAPI-Proxy-Secret` + `X-RapidAPI-User`). Neither is something an

    integrator sends by hand. ## Targets and what each supports


    | target | page | num | safe |

    | --- | --- | --- | --- |

    | `google_search` | 1–5 | 1–20 | off, moderate, strict |

    | `bing_search` | 1 only | 1–20 | off, moderate, strict |

    | `duckduckgo_search` | 1 only | 1–10 | not supported |

    | `yahoo_search` | 1 only | 1–10 | off, moderate, strict |

    | `brave_search` | 1–5 | 1–20 | off, moderate, strict |

    | `yandex_search` | 1–5 | 1–10 | not supported |


    Anything outside a target''s row answers `400 unsupported_parameter`:

    `bing_search` refuses `page` above 1; `duckduckgo_search` refuses `page`

    above 1, `num` above 10 and any `safe` but `off`; `yahoo_search` refuses

    `page` above 1 and `num` above 10; `brave_search` refuses `page` above 5;

    `yandex_search` refuses `num` above 10 and any `safe` but `off`. A `geo` outside

    the supported list answers `400 unsupported_geo` with the list in `details`. ## Credits


    Every search costs one credit: one for `GET /v1/query`, one per row of

    `POST /v1/bulk`. A cache hit costs the same as a fresh search. An upstream

    failure (502 / 504) is still charged: the search was run and only the answer

    is missing. A request refused with 400 or 402, and a failure on our side

    (500), cost nothing. ## Plans and quotas


    Every account starts on the trial: 100 requests, granted once per email

    address, that never reset. The trial has no period at all — nothing rolls

    over, so there is no reset to wait for. A paid plan''s quota is measured over its subscription''s billing cycle, which

    renews monthly on the day the subscription started rather than on the 1st. `X-Quota-Reset` and `period.end` carry the exact moment it rolls over; read

    the reset off those rather than deriving it from a calendar. An account on a

    paid plan with no subscription cycle behind it — a RapidAPI subscriber, a

    plan set by hand — is measured over the calendar month in UTC instead,

    resetting at `00:00:00Z` on the 1st. | plan | $ / month | requests | extra requests | concurrency |

    | --- | --- | --- | --- | --- |

    | Trial | 0 | 100, once, for life | — | 1 concurrent request |

    | Starter | 9 | 5,000 / month | credit packs at $1.50 per 1,000 | 2 concurrent requests |

    | Growth | 49 | 75,000 / month | credit packs at $0.80 per 1,000 | 5 concurrent requests |

    | Business | 99 | 200,000 / month | credit packs at $0.60 per 1,000 | 10 concurrent requests |

    | Custom | contact us | quoted | quoted | 20 concurrent requests |


    A plan costs the same bought direct as it does through RapidAPI. Plans

    bought direct are sold through Polar, our Merchant of Record: Polar takes

    the payment, handles tax and issues the invoice, and the subscription,

    payment methods and invoice history are managed in its customer portal. ## Credit packs


    Every plan is hard-limited — nothing is ever served on credit.'
  contact:
    name: SerpResult support
    email: team@serpresult.com
  license:
    name: Proprietary
    url: https://serpresult.com/legal/terms
servers:
- url: https://api.serpresult.com
  description: Production.
- url: http://localhost:8787
  description: Local `wrangler dev`.
security:
- bearerAuth: []
- sessionCookie: []
tags:
- name: API Keys
  description: Mint, list, rename, rotate and revoke secret keys. Session only.
paths:
  /v1/api-keys:
    get:
      tags:
      - API Keys
      operationId: listApiKeys
      summary: List API keys
      description: '**Session only.** The account''s active keys, newest first. Revoked keys are not listed. The secret itself is never returned.'
      security:
      - sessionCookie: []
      responses:
        '200':
          description: The keys.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListApiKeysResponse'
              example:
                keys:
                - id: key_21bdefca3efe49d8a0e6e8db9e3e8849
                  name: Production
                  key_type: live
                  prefix: REDACTED_STRIPE_KEY
                  last4: sow0
                  created_at: '2026-09-08T10:59:45.431Z'
                  last_used_at: null
                - id: key_694d09fd793a451e8319a7859136b46b
                  name: Docs test key
                  key_type: test
                  prefix: REDACTED_STRIPE_KEY
                  last4: GZCQ
                  created_at: '2026-09-08T10:58:37.902Z'
                  last_used_at: '2026-09-08T10:59:36.333Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
      - API Keys
      operationId: createApiKey
      summary: Create an API key
      description: '**Session only.** Mints a key. The plaintext `key` is in this response and nowhere else; store it on receipt.'
      security:
      - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
            example:
              name: Production
              key_type: live
      responses:
        '201':
          description: The key was minted.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MintedApiKeyResponse'
              example:
                key: REDACTED_STRIPE_KEY
                api_key:
                  id: key_21bdefca3efe49d8a0e6e8db9e3e8849
                  name: Production
                  key_type: live
                  prefix: REDACTED_STRIPE_KEY
                  last4: '0000'
                  created_at: '2026-09-08T10:59:45.431Z'
                  last_used_at: null
        '400':
          $ref: '#/components/responses/ValidationBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/api-keys/{id}:
    parameters:
    - $ref: '#/components/parameters/apiKeyId'
    patch:
      tags:
      - API Keys
      operationId: renameApiKey
      summary: Rename an API key
      description: '**Session only.** Changes the label. The secret is unchanged.'
      security:
      - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameApiKeyRequest'
            example:
              name: Production (EU)
      responses:
        '200':
          description: The renamed key.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
              example:
                api_key:
                  id: key_21bdefca3efe49d8a0e6e8db9e3e8849
                  name: Production (EU)
                  key_type: live
                  prefix: REDACTED_STRIPE_KEY
                  last4: sow0
                  created_at: '2026-09-08T10:59:45.431Z'
                  last_used_at: null
        '400':
          $ref: '#/components/responses/ValidationBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ApiKeyNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
      - API Keys
      operationId: revokeApiKey
      summary: Revoke an API key
      description: '**Session only.** The key stops authenticating within a minute. Its query history stays readable and it keeps appearing in usage breakdowns.'
      security:
      - sessionCookie: []
      responses:
        '204':
          description: Revoked. No body.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ApiKeyNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/api-keys/{id}/rotate:
    parameters:
    - $ref: '#/components/parameters/apiKeyId'
    post:
      tags:
      - API Keys
      operationId: rotateApiKey
      summary: Rotate an API key
      description: '**Session only.** Revokes this key and mints a replacement with the same

        name and type. The replacement has a **new id** — read it from

        `api_key.id` in the response and use that for any later rename, rotate

        or revoke; the old id answers `404 not_found` from now on. The old secret

        stops authenticating within a minute; the new plaintext `key` is in this

        response and nowhere else.'
      security:
      - sessionCookie: []
      responses:
        '201':
          description: The new secret and the key it now belongs to.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MintedApiKeyResponse'
              example:
                key: REDACTED_STRIPE_KEY
                api_key:
                  id: key_1a2dbebce87044fcb46aa94671fe8e59
                  name: Production (EU)
                  key_type: live
                  prefix: REDACTED_STRIPE_KEY
                  last4: '0000'
                  created_at: '2026-09-08T10:59:46.807Z'
                  last_used_at: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ApiKeyNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    ValidationBadRequest:
      description: A parameter or body field failed validation (`invalid_request`). `issues` lists each field.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error: invalid_request
            message: name must be between 1 and 64 characters.
            request_id: 7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90
            issues:
            - field: name
              message: name must be between 1 and 64 characters.
    ApiKeyNotFound:
      description: No key with that id on this account, or it is already revoked (`not_found`).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error: not_found
            message: No API key with that id exists on this account.
            request_id: 7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90
    Unauthorized:
      description: No accepted credential (`unauthorized`). A session-only route answers this to a bearer key; the demo header answers this when a credential rides along with it.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error: unauthorized
            message: API key is not valid.
            request_id: 7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90
    InternalError:
      description: Something failed on our side (`internal_error`). The detail is in our logs under `request_id`. Nothing is charged.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error: internal_error
            message: The request could not be completed.
            request_id: 7d1c2f34-1b7e-4d2a-9c33-1f6f0e2b8a90
  schemas:
    ErrorCode:
      type: string
      description: 'Every code the API emits.

        - `invalid_request` — validation failed; `issues` lists the fields.

        - `unsupported_geo` — `geo` is not supported; `details` lists the supported codes.

        - `unsupported_parameter` — the target cannot serve `page`, `num` or `safe` as sent.

        - `unauthorized` — no accepted credential.

        - `not_found` — unknown route, or an API key id not on this account.

        - `rate_limited` — per-minute limit spent.

        - `quota_exceeded` — the period''s quota and the credit balance are both spent. Not charged.

        - `upstream_error` — the search provider failed. Charged.

        - `upstream_timeout` — the search provider did not answer in time. Charged.

        - `no_subscription` — a plan change or a credit-pack purchase was asked for on an account with no active subscription.

        - `plan_unchanged` — a plan change was asked for on the plan the account is already on.

        - `billing_unavailable` — purchases are closed on this deployment: either it is not wired to Polar, or direct checkout is switched off while the same plans are sold on RapidAPI.

        - `internal_error` — a fault on our side. Not charged.

        '
      enum:
      - invalid_request
      - unsupported_geo
      - unsupported_parameter
      - unauthorized
      - not_found
      - rate_limited
      - quota_exceeded
      - upstream_error
      - upstream_timeout
      - no_subscription
      - plan_unchanged
      - billing_unavailable
      - internal_error
    MintedApiKeyResponse:
      type: object
      required:
      - key
      - api_key
      properties:
        key:
          type: string
          description: The plaintext secret. Shown once.
          pattern: ^sk_(live|test)_[A-Za-z0-9_-]{43}$
        api_key:
          $ref: '#/components/schemas/ApiKey'
    ApiKeyResponse:
      type: object
      required:
      - api_key
      properties:
        api_key:
          $ref: '#/components/schemas/ApiKey'
    RenameApiKeyRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
    CreateApiKeyRequest:
      type: object
      required:
      - name
      - key_type
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          description: A label. Trimmed.
        key_type:
          type: string
          enum:
          - live
          - test
          description: '`live` keys get the `sk_live_` prefix, `test` keys get `sk_test_`. Both are held to the account plan''s rate and spend the same quota.'
    ErrorEnvelope:
      type: object
      description: The shape of every error response.
      required:
      - error
      - message
      - request_id
      properties:
        error:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Human-readable, safe to show to an end user.
        request_id:
          type: string
          format: uuid
          description: Same value as the `X-Request-Id` header.
        details:
          type: array
          description: On `unsupported_geo` only, the supported country codes.
          items:
            $ref: '#/components/schemas/Geo'
        issues:
          type: array
          description: On `invalid_request` from a validator, one entry per failed field.
          items:
            type: object
            required:
            - field
            - message
            properties:
              field:
                type: string
                description: Dotted path of the field. Empty for the whole input.
              message:
                type: string
    ApiKey:
      type: object
      description: A key as its owner sees it. The secret is never included.
      required:
      - id
      - name
      - key_type
      - prefix
      - last4
      - created_at
      - last_used_at
      properties:
        id:
          type: string
          pattern: ^key_[0-9a-f]{32}$
        name:
          type: string
        key_type:
          type: string
          enum:
          - live
          - test
        prefix:
          type: string
          description: The first characters of the secret, enough to recognise it in a config file.
        last4:
          type: string
          description: The last four characters of the secret.
        created_at:
          type: string
          format: date-time
        last_used_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Updated at most once every five minutes of use.
    Geo:
      type: string
      description: 'A supported country, as an ISO 3166-1 alpha-2 code. Results are

        localized to this country, the same ones a user searching there would

        see, and the code also picks the default `locale`.

        '
      enum:
      - us
      - in
      - gb
      - ca
      - au
      - de
      - fr
      - sg
      - ae
      - jp
      - ad
      - af
      - ag
      - al
      - am
      - ao
      - ar
      - at
      - aw
      - az
      - ba
      - bb
      - bd
      - be
      - bf
      - bg
      - bh
      - bi
      - bj
      - bn
      - bo
      - br
      - bs
      - bw
      - by
      - bz
      - cd
      - cg
      - ch
      - ci
      - cl
      - cm
      - cn
      - co
      - cr
      - cu
      - cv
      - cy
      - cz
      - dk
      - do
      - dz
      - ec
      - ee
      - eg
      - es
      - et
      - fi
      - fj
      - fm
      - fo
      - ga
      - gd
      - ge
      - gf
      - gg
      - gh
      - gm
      - gp
      - gq
      - gr
      - gt
      - gu
      - gy
      - hk
      - hn
      - hr
      - ht
      - hu
      - id
      - ie
      - il
      - iq
      - ir
      - is
      - it
      - jm
      - jo
      - ke
      - kg
      - kh
      - km
      - kn
      - kr
      - kw
      - ky
      - kz
      - la
      - lb
      - lc
      - lk
      - lr
      - ls
      - lt
      - lu
      - lv
      - ly
      - ma
      - md
      - me
      - mg
      - mk
      - ml
      - mm
      - mn
      - mo
      - mp
      - mq
      - mr
      - mt
      - mu
      - mv
      - mw
      - mx
      - my
      - mz
      - na
      - nc
      - ne
      - ng
      - ni
      - nl
      - 'no'
      - np
      - nz
      - om
      - pa
      - pe
      - pf
      - pg
      - ph
      - pk
      - pl
      - pr
      - ps
      - pt
      - pw
      - py
      - qa
      - re
      - ro
      - rs
      - ru
      - rw
      - sa
      - sb
      - sd
      - se
      - si
      - sk
      - sl
      - sn
      - so
      - sr
      - st
      - sv
      - sy
      - sz
      - td
      - tg
      - th
      - tj
      - tl
      - tn
      - to
      - tr
      - tt
      - tw
      - tz
      - ua
      - ug
      - uy
      - uz
      - vc
      - ve
      - vg
      - vi
      - vn
      - vu
      - ye
      - za
      - zm
      - zw
      default: us
    ListApiKeysResponse:
      type: object
      required:
      - keys
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/ApiKey'
  headers:
    X-Request-Id:
      description: The id of this request, identical to `request_id` in any error body. Quote it in a support request.
      schema:
        type: string
        format: uuid
  parameters:
    apiKeyId:
      name: id
      in: path
      required: true
      description: The key id, as returned by list or create.
      schema:
        type: string
        pattern: ^key_[0-9a-f]{32}$
      example: key_0f3ab2f0d0c845feb2cbb2dbbd1b2fa7
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A secret key from the dashboard: `Authorization: Bearer sk_live_…` or

        `Bearer sk_test_…`. Both are held to the account plan''s rate — 60 a

        minute on the trial, up to 1200 on a custom plan — and both spend the

        same quota. Accepted on `/v1/query`, `/v1/bulk`, `/v1/me` and the MCP

        endpoint `POST /mcp` only; a session-only route answers 401 to a key.

        '
    sessionCookie:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: 'The dashboard''s session cookie (`__Secure-better-auth.session_token` when

        served over HTTPS). Accepted everywhere a key is, and the only credential

        the session-only routes take. On the search routes it gets the plan''s

        per-minute limit or 120, whichever is higher.

        '
    demoOrigin:
      type: apiKey
      in: header
      name: X-Demo-Origin
      description: 'The marketing site''s keyless hero search. The header must equal the

        deployment''s configured demo origin, and the request must carry no

        `Authorization` header and no session cookie — a credential sent beside

        it is refused rather than re-metered. The principal is the client IP,

        limited to 5 requests a minute, with no account behind it. Accepted on

        `/v1/query` and `/v1/bulk`.

        '
    rapidApiProxy:
      type: apiKey
      in: header
      name: X-RapidAPI-Proxy-Secret
      description: 'Requests relayed by the RapidAPI marketplace. The proxy injects

        `X-RapidAPI-Proxy-Secret` (compared in constant time against the

        deployment''s secret) and `X-RapidAPI-User` (the marketplace account the

        call is attributed to). Integrators never send these themselves. When

        the marketplace secret is not configured, or the marketplace account

        mapping has not landed, every request on this path answers

        `401 unauthorized` — this branch currently answers 401.

        '