FaithAPIDocumentation
Public documentation

Start with FaithAPI's public surface.

The API organizes instances, messages, and events into versioned contracts. Evaluate the integration before requesting credentials.

Make the first request

Authentication

Send the API key only from server-side code. It identifies the tenant and grants explicit scopes; never expose it in a browser or distributed client application.

HTTP
Authorization: Bearer faith_live_...
Idempotency-Key: order-418-message-1
Access is denied by default.Reads and mutations require explicit scopes such as instances:read, instances:write, and messages:send.

First request

Create a logical instance, then request its start. Creation does not open a channel connection automatically.

TypeScript
import { FaithAPI } from "@faithapi/sdk-typescript";

const faith = new FaithAPI({ apiKey: process.env.FAITH_API_KEY! });
const instance = await faith.instances.create({ name: "Primary operation", provider: "whatsapp" });
await faith.instances.start(instance.id, { idempotencyKey: `start-${instance.id}` });

Instances

An instance groups identity, lifecycle, and connection context. The public flow is explicit: create, start, pair, operate, and stop. desired_state records client intent; observed_state changes only from processed connector events.

Messages

Submitting a message returns 202 Accepted after the command is persisted. This confirms durable acceptance by FaithAPI—not channel sending or delivery.

TypeScript
await faith.messages.send(instance.id, { type: "text", to: "+15551234567", text: "Hello" }, { idempotencyKey: "order-418-message-1" });

Idempotency

Every relevant mutation requires an Idempotency-Key. Repeating the same operation with the same payload returns the same durable result. Reusing a key with different input is rejected.

Webhooks

Events are delivered at least once and without global ordering. Return 2xx after persisting evidence and deduplicate by event or aggregate identifier.

Verify signatures

TypeScript
import { verifyWebhookSignature } from "@faithapi/sdk-typescript";
const valid = verifyWebhookSignature({ rawBody, timestamp, signature, secret: process.env.FAITH_WEBHOOK_SECRET! });

Requests include Faith-Signature, Faith-Timestamp, and a stable event identifier. Verify against the raw body before parsing JSON.

TypeScript SDK

The SDK validates responses with the same public API contracts, does not perform automatic retries, and exposes stable errors through FaithApiError.

Errors and states

Errors include an HTTP status, stable code, safe message, and requestId. Treat 401 as invalid credentials, 403 as missing scope, 409 as state or idempotency conflict, and 429 as a temporary limit.

Main endpoints

This reference covers the most common integration surface. Compatibility administration routes require additional operator identity and scopes.

MethodRoutePurpose
GET/v1/instancesList tenant instances
POST/v1/instancesCreate a logical instance
POST/v1/instances/{id}/startRequest instance start
POST/v1/instances/{id}/stopRequest instance stop
GET/v1/instances/{id}/pairingRead current pairing state
POST/v1/instances/{id}/pairing/codeRequest a pairing code
POST/v1/instances/{id}/messagesSubmit a message
GET/v1/messages/{messageId}Read a message
GET · POST/v1/webhooksList or create endpoints
GET · PATCH · DELETE/v1/webhooks/{id}Manage an endpoint
GET/v1/webhook-deliveriesList deliveries
POST/v1/webhook-deliveries/{id}/replayRequest redelivery
GET/v1/operations/overviewOperational overview
GET/v1/operations/timelineOperational timeline

Read first. Request access when it makes sense.

Documentation is open. Credentials, environment URL, and deployment model are defined with Onefold.

Request technical access