Letterbook
All docs

Letterbook Docs

Connect an internal API

Expose safe server-side actions for account updates, entitlement checks, and operational workflows.

Last updated June 25, 2026

What this guide covers#

Connect narrow internal API endpoints so Letterbook can check or update account data without unrestricted system access.

Internal API actions are useful when the AI needs live application context or when a support resolution requires a controlled operation in your product.

Setup steps#

  1. Identify the support questions or actions that require your internal system.
  2. Prefer read-only endpoints for the first version.
  3. Define input and output schemas for each endpoint.
  4. Add authentication and authorization.
  5. Restrict access to support-safe fields and operations.
  6. Log every call with the conversation and customer context.
  7. Require approval for destructive or customer-visible actions.
  8. Test success, validation error, permission error, and timeout cases.

Guardrails#

  • Read-only endpoints by default
  • Idempotency keys for actions
  • Clear error messages for support agents
  • Rate limits and retries
  • Separate endpoints for separate actions
  • No arbitrary database queries from support workflows
  • No secrets or credentials in responses

Read endpoints#

Read endpoints help the AI answer account-specific questions. Examples:

  • Get current plan and entitlement limits
  • Check whether a feature flag is enabled
  • Fetch recent usage or sync status
  • Look up account ownership or team membership
  • Retrieve the latest application error associated with a customer

These endpoints should return only the fields needed for support. If the full internal record contains sensitive or irrelevant data, create a support-specific view or response shape.

Write endpoints#

Write endpoints change something in your product. Examples:

  • Extend a trial
  • Recalculate entitlements
  • Re-send an invite
  • Apply a courtesy credit
  • Trigger a background repair job

For write endpoints, require human approval unless the action is low risk and thoroughly tested. Use idempotency keys so retries do not apply the same action twice.

Schema design#

Use predictable schemas. Avoid free-form commands that let the AI or a teammate request arbitrary behavior.

Good:

{
  "customer_id": "cus_123",
  "trial_extension_days": 7,
  "reason": "Customer could not access account during outage"
}

Risky:

{
  "command": "extend trial if it seems reasonable"
}