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/contractsimport { 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.createpartner.sites.sitemaps.action.createpartner.sites.registered_host.beginpartner.teams.createpartner.users.api_keys.createrealtime.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.