serpresult-com Account API

openapi: 3.2.0
info:
  title: Serpresult Com Account API
  version: 1.0.0
  contact:
    name: SerpResult support
    email: team@serpresult.com
  license:
    name: Proprietary
    url: https://serpresult.com/legal/terms
  description: 'Operations tagged Account across 2 of this provider''s published API definitions: api-serpresult-com-openapi.json, docs-serpresult-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.serpresult.com
  description: Production.
- url: http://localhost:8787
  description: Local `wrangler dev`.
security:
- bearerAuth: []
- sessionCookie: []
tags:
- name: Account
  description: The account behind the calling credential. Accepts an API key or a session cookie. Costs no credits.
paths:
  /v1/me:
    get:
      tags:
      - Account
      operationId: getMe
      summary: Retrieve your account
      description: 'The account behind the calling credential: its email, plan, the credits

        it can still spend and, for an API key, the key''s own name and mode. The

        recommended connection test: a `200` means the credential is valid.


        Costs 0 credits and is not written to the query history. It counts as one

        hit against the caller''s per-minute rate limit. A dashboard session gets

        `api_key: null`.'
      responses:
        '200':
          description: The account.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
              example:
                email: jane@acme.com
                plan: growth
                credits_available: 48210
                api_key:
                  id: key_3f2a9c1e7b4d4e8a9f602c1d8e5b7a90
                  label: Zapier
                  mode: live
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://api.serpresult.com
      description: Production.
    - url: http://localhost:8787
      description: Local `wrangler dev`.
components:
  responses:
    RateLimited:
      description: The credential's per-minute limit is spent (`rate_limited`). Wait `Retry-After` seconds.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error: rate_limited
            message: Rate limit of 20 requests per minute exceeded. Retry in 37 seconds.
            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:
    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
    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
    Me:
      type: object
      required:
      - email
      - plan
      - credits_available
      - api_key
      properties:
        email:
          type: string
          description: The account's email address. Empty for a marketplace subscriber.
        plan:
          $ref: '#/components/schemas/PlanId'
          description: The plan the account is on.
        credits_available:
          type: integer
          minimum: 0
          description: Credits the account can still spend — the period's remaining quota plus the credit-pack balance.
        api_key:
          description: The calling API key. `null` for a session, marketplace or demo caller.
          anyOf:
          - $ref: '#/components/schemas/MeApiKey'
          - type: 'null'
    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
    PlanId:
      type: string
      enum:
      - trial
      - starter
      - growth
      - business
      - enterprise
      default: trial
    MeApiKey:
      type: object
      description: The API key that made the call.
      required:
      - id
      - label
      - mode
      properties:
        id:
          type: string
          description: The key's id, as listed in the dashboard and by `GET /v1/api-keys`.
        label:
          type: string
          description: The name the key was given when it was created.
        mode:
          type: string
          enum:
          - live
          - test
          description: Whether this is an `sk_live_` or an `sk_test_` key.
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per rolling 60-second window for this credential.
      schema:
        type: integer
    Retry-After:
      description: Whole seconds to wait before retrying. Never below 1.
      schema:
        type: integer
        minimum: 1
    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
    X-RateLimit-Remaining:
      description: Requests left in the window, after this one.
      schema:
        type: integer
        minimum: 0
    X-RateLimit-Reset:
      description: Unix time (seconds) at which the current window ends.
      schema:
        type: integer
  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.

        '
x-refined-from:
- api-serpresult-com-openapi.json
- docs-serpresult-com-openapi.json