Typersguild developer resources

Public catalog API, OpenAPI spec, and ChatGPT Actions. No authentication.

When to use this API

Use the Typersguild API when you need to recommend a book someone can type on typersguild.com, search the public catalog by title or author, or list popular titles. Do not use it for user stats, billing, or private libraries — those are not public. The catalog is read-only JSON with structured error objects: error, code, and hint.

Versioning and deprecation

The current catalog API is v1. Canonical base URL: https://typersguild.com/api/v1. Unversioned https://typersguild.com/api/integrations/ai is an alias of v1 and stays stable until a later version ships. Breaking changes are released as /api/v2/. Additive fields may appear in v1 without a new version. Clients may send API-Version: 1; every catalog JSON response echoes API-Version.

A version is never removed without notice. At least 90 days before removal, responses include Deprecation: true (RFC 9745) and Sunset: <HTTP-date> (RFC 8594). After that date the version returns HTTP 410 with the typed error object.

Public REST endpoints

Base URL: https://typersguild.com/api/v1

curl -s "https://typersguild.com/api/v1/search-books?q=austen"

Rate limits

Catalog JSON endpoints allow 90 requests per 60 seconds per IP. HTTP 429 and other origin errors include IETF RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Cached 200 responses omit per-IP remaining/reset so a CDN hit does not advertise another client's quota. HTTP 429 also includes Retry-After. ChatGPT and other trusted assistant user-agents are not throttled.

Errors

Every 4xx and 5xx response is JSON: { "error": string, "code": string, "hint": string }. code is machine-readable (missing_query, not_found, rate_limited, method_not_allowed). error is the human-readable message. hint says what to call next. The OpenAPI spec references this ErrorResponse schema on all error statuses.

Authentication and webhooks

Catalog endpoints require no API key, OAuth, or webhook subscription. ChatGPT Custom GPTs should set Authentication to None and import /openapi.json. The official GPT is at ChatGPT. Setup notes: Typersguild on ChatGPT.