Index of every page on this site: llms.txt
Skip to content

Hosted HTTP

Import createGscdumpV1Client from @gscdump/sdk/v1. Each registered operation has a typed convenience method. You can also pass its operation ID to client.execute().

The client validates request and response payloads against the generated contracts.

API specifications

Generate OpenAPI and AsyncAPI documents from the published contracts package:

pnpm add @gscdump/contracts
import { writeFile } from 'node:fs/promises'
import { createGscdumpV1Documents } from '@gscdump/contracts/v1'

for (const [name, document] of Object.entries(createGscdumpV1Documents())) {
  await writeFile(name, JSON.stringify(document, null, 2))
}

The function returns three OpenAPI documents: partner, analytics, and realtime HTTP. It also returns the realtime AsyncAPI document. Each document defines inputs, responses, scopes, and operation semantics for your installed package version.

Errors

API failures use one JSON envelope:

{
  "error": {
    "code": "site_not_found",
    "message": "Site not found",
    "requestId": "req_01",
    "retryable": false,
    "details": {}
  }
}

Branch on code and retryable. Treat message as display text. Include requestId when reporting a failure. The SDK exposes the same fields through GscdumpV1Error:

import {
  createGscdumpV1Client,
  isGscdumpV1Error,
} from '@gscdump/sdk/v1'

const gscdump = createGscdumpV1Client({
  credential: () => process.env.GSCDUMP_API_KEY!,
})

const result = await gscdump.getSiteIndexing({
  params: { siteId: 's_01' },
  query: {},
}).catch((error: unknown) => {
  if (isGscdumpV1Error(error)) {
    console.error(error.code, error.requestId, error.retryable)
    return null
  }
  throw error
})

Each OpenAPI operation lists its closed API error set in x-gscdump-errors. The SDK also reports local credential, request, transport, and response validation failures with the same tagged error class.

Successful responses use { "data": ..., "meta": ... }. meta includes the request ID, surface, and wire version. Every HTTP response also carries x-request-id, GSCdump-API-Version: 1.0, Cache-Control: private, no-store, and Vary: Authorization.

Rate limits

The host applies rate limits per authenticated principal and operation. Use the response headers to determine the remaining quota and reset time.

Quota-evaluated responses include RateLimit-Policy and RateLimit. On 429 rate_limited, wait for the Retry-After duration. Treat it as authoritative. If the limiter is unavailable, the host fails closed with a retryable 503 internal_error and Retry-After: 5.

The SDK honors Retry-After when the operation descriptor allows a retry.

Idempotency and retries

The OpenAPI x-gscdump-semantics object records whether an operation is idempotent and whether the SDK may retry it. Check each operation before retrying it.

Six mutations are non-idempotent and use retry: "never":

  • partner.sites.indexing.inspect.create
  • partner.sites.sitemaps.action.create
  • partner.sites.registered_host.begin
  • partner.teams.create
  • partner.users.api_keys.create
  • realtime.tickets.create

The SDK does not automatically retry those five operations. After an ambiguous network failure, read authoritative state before deciding whether to issue another mutation. A realtime reconnect always requests a new ticket because tickets are single-use.

For operations marked retry: "idempotent", the SDK defaults to three total attempts and caps configuration at five. It retries network failures and API errors whose envelope says retryable: true. The backoff starts at 250 ms, caps at two seconds, and waits longer when Retry-After requires it.

V1 currently has no public result-replay contract for Idempotency-Key. A client-supplied key does not make a non-idempotent operation safe to retry.