Docs · REST API

Guest Talk REST API reference.

This reference lists the resource families in the Guest Talk API v1, the operations available on each, and the conventions that apply across the surface. The complete OpenAPI 3.1 specification is published at https://api.talkg.fabriza.org/v1/openapi.json and refreshed on every release.

Authentication

Every request must include an Authorization header. Two forms are supported:

Authorization: Bearer sk_live_abcdef123456... (long-lived workspace API key) Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX... (short-lived OAuth 2.0 access token)

Long-lived keys are for workspace-owned automations (nightly report exports, in-house connectors). OAuth 2.0 tokens are for marketplace apps that act on behalf of a specific workspace after user consent. The OAuth flow follows RFC 6749 with PKCE required for all clients.

Resource families

/reservations — create, read, update, cancel reservations. Sub-resources: guests, folios, messages, notes.
/guests — guest profiles, marketing consent, tags, history.
/rooms and /room-types — inventory model.
/rates and /rate-plans — base and derived rate plans, per-day pricing.
/channels — OTA connections and parity status.
/folios and /payments — billing.
/messages and /templates — guest messaging.
/tasks — operations and housekeeping tasks.
/reports — scheduled and on-demand reports.
/users and /roles — workspace user management.
/webhooks — webhook subscriptions (see /docs/webhooks).

Pagination

List endpoints return paginated results using cursor-based pagination. The response envelope is:

{ "data": [ ... ], "next_cursor": "eyJpZCI6MTAwMTIzfQ", "has_more": true }

To fetch the next page, pass ?cursor=eyJpZCI6MTAwMTIzfQ. Page size defaults to 50 and can be up to 200 via ?limit=. Offset pagination is not supported (it does not scale and creates duplicated or missing results under concurrent mutation).

Filtering and sorting

List endpoints support a small set of filter parameters documented per endpoint. Common filters: created_after, created_before, updated_after, status. Sorting is via ?sort=field,-other_field where the leading minus indicates descending order.

Idempotency

All state-changing operations accept an Idempotency-Key header. Guest Talk stores the request and response for 24 hours keyed by that value; a repeat request with the same key returns the original response. Use a random UUID per logical operation to make retries safe.

Errors

Errors are returned with the appropriate HTTP status code and a JSON body:

{ "error": { "code": "rate_limit_exceeded", "message": "Too many write requests. Slow down.", "docs_url": "https://talkg.fabriza.org/docs/error-codes#rate_limit_exceeded" } }

The code field is the canonical enumerated error; the message is human-friendly and may change; the docs_url links to the full error catalogue.

Versioning

Guest Talk pins the API version in the URL. Non-breaking additions (new fields, endpoints, optional parameters) apply in place. Breaking changes create a new version (v2), and the prior version is supported for a minimum of 24 months from the successor's release. Deprecations are announced by email to workspace owners at least 12 months before removal.

SDKs

Official SDKs are published for TypeScript, Python and Ruby. All three are generated from the OpenAPI specification and updated on every API release. See the Guest Talk GitHub organisation for source. Community SDKs exist for PHP, Java, Go and .NET; we do not maintain them but link to them from the documentation.

Sandbox

Every workspace can request a sandbox mirror. Sandbox uses the same API surface, returns fake data, and never triggers real messages or payments. Sandbox keys are prefixed sk_test_ for easy identification. Sandbox is unrated for developer experimentation.

SLA

The API SLA is 99.9 percent monthly uptime. Actual uptime is published on the status page at status.talkg.fabriza.org. Where uptime falls below 99.9 percent for a calendar month, service credits are applied as documented in the Refund and Cancellation Policy.