Skip to main content
The Go client covers the statutes, session law, watch, board, credit and pricing operations of the US Data API and mirrors the behavior of the Python SDK. The operations without a method yet are listed in the SDKs overview. For the options shared by all SDKs, see the SDKs overview.

Install

Requires Go 1.23 or newer, because the paging iterators use iter.Seq2. The module lives in the go/ subdirectory of the repository, so its path ends in /go and its release tags are go/vX.Y.Z. Install the latest release:
Source: Vaquill-AI/vaquill-sdks, go/ on GitHub.

Quickstart

Every method takes a context.Context first, returns a typed value and an error, and never panics. Optional request fields are pointers, so use vaquill.Ptr("wa"). Fields that accept one value or a list use vaquill.StringOrList{"wa", "ca"}. Client options: WithAPIKey, WithBaseURL, WithTimeout (0 disables), WithMaxRetries, WithHTTPClient, WithDefaultHeaders, WithUserAgentSuffix, WithMaxCredits, WithAutoIdempotencyKeys, WithLogger. Per-call options: WithRequestTimeout, WithRequestMaxRetries, WithIdempotencyKey, WithRequestHeader, WithResponse. Read the status, request id and credits of a call with WithResponse.
Header, Body, RateLimit and CreditsConsumed are on the same value. CreditsConsumed is the top-level creditsConsumed of the body. When the top level has no number, Go reads meta.creditsConsumed, because the watch change diff route reports its charge there. CreditsChargedThisCall is zero on an idempotent replay and feeds WithMaxCredits. client.Raw sends any request and returns the undecoded body.

Errors

All SDK errors implement vaquill.Error. HTTP failures are typed per status and per machine code, and every one unwraps to *vaquill.APIError, which carries StatusCode, Code, RequestID, Retryable, RetryAfterSeconds, Errors, Body and Headers.
Other types: ConnectionError, TimeoutError, ResponseParseError (a malformed 2xx body), SpendGuardError, ConfigError and WebhookVerificationError. A 422 message ends with the first validation reasons from errors[]. IdempotencyKeyReused is also an unprocessable-entity error, and IdempotencyInProgress is also a conflict.

Retries and idempotency

The SDKs retry 408, 429 and 5xx responses, plus a 409 only for idempotency_in_progress. Connection errors and timeouts are retried when it is safe to do so. The default is 2 retries, and setting the retry limit to 0 turns retries off. Backoff starts at 0.5 seconds, doubles to an 8 second cap and is scaled down by 0 to 25 percent jitter. The wait comes from the retry-after-ms header first, then Retry-After (seconds or an HTTP date), then the body’s retryAfterSeconds. A wait above 120 seconds is not slept: the error is raised at once. Never retried: a 402 insufficient_credits, daily_cap_exceeded, any other 4xx, and anything the server marks retryable: false. Go specifics:
  • 501 is not retried.
  • A transport error that may have reached the server is retried only for GET and HEAD, or when an idempotency key is set.
  • A 5xx on a charged call is not retried without an idempotency key.
Each charged call sends one generated Idempotency-Key, reused on every retry of that call. When the server honours the key it replays the stored response instead of charging again, and the response reports that it was replayed. Pass your own key to choose it. Charged POSTs get a generated UUID key unless you pass one.
Keys must be 16 to 255 visible ASCII characters. An empty or invalid key is rejected before any request. ResponseInfo.IdempotentReplayed tells you the server replayed a stored response, so nothing new was charged.

Spend guard

Once the cap is reached, the next charged call fails with *vaquill.SpendGuardError without sending a request. The guard is exact: how it stays exact is on the overview. client.CreditsSpent() reads the running total.

Pagination and batch helpers

Paginated endpoints return a *Paginator[T] built on iter.Seq2.
Pages() yields whole pages and Collect() returns a slice.
Charged endpoints spend credits on every page. Always set WithMaxPages or WithMaxItems.
Truncated reports that a guard stopped the walk early. Stuck reports that the server repeated its offset or cursor, or answered an empty page with hasMore: true, and the SDK stopped instead of spending on the same page again. Iterators: Statutes.IterSearch, IterDivisions, IterSectionChanges; SessionLaws.IterSearch, IterList, IterBody, IterChanges; Boards.IterList; Watches.IterList, IterChanges. Batch helpers split large inputs, remove duplicates and derive a per-chunk idempotency key.

Webhooks

Deliveries follow the Standard Webhooks scheme. Verify the raw request body, never a re-encoded one.
Secrets are whsec_ plus base64. Pass several secrets to VerifyWebhookSecrets or UnwrapWebhookSecrets while rotating. An empty or blank secret, including a bare whsec_, or an empty secret list, returns ErrEmptyWebhookSecret. It is a configuration error, not a signature failure. A whsec_ secret whose remainder is not valid base64 returns ErrInvalidWebhookSecret instead of using the text as the key. Test both with errors.Is. The default timestamp tolerance is 5 minutes (WithWebhookTolerance). WithLegacySignature accepts the older X-Vaquill-Signature header, which has no replay protection. SignWebhook produces headers for your own tests. See Alerts for the payload and delivery behavior.

Versioning

The SDK follows semantic versioning, and vaquill.Version holds the version. Requests carry User-Agent: vaquill-go/<version>. The released version is in the SDKs overview table. While the major version is 0, minor releases may change the API. A server Deprecation or Sunset header makes the client log one warning per route. vaquill.Operations lists every operation with its method, path and whether it is charged. Run the tests from a checkout of the repository.
Last modified on November 7, 2026