GoFaceless
gofaceless

GoFaceless Developer Platform

Build video workflows that agents can operate safely

Use the GoFaceless REST API, OpenAPI schema, OAuth-protected hosted MCP server, webhooks, and companion CLI to create and supervise durable video sessions. The same production, authorization, billing, and recovery contracts power the web studio and every external integration.

Start with the machine-readable contract

The external REST API is served from https://api.gofaceless.ai/api/v1. Its public OpenAPI 3.1 document contains typed parameters, request bodies, response schemas, stable operation identifiers, problem-detail errors, authentication, and version headers.

GoFaceless OpenAPI schemaJSON, public, OpenAPI 3.1GoFaceless MCP manifestStreamable HTTP tools and OAuth discovery

Authenticate without putting secrets in content

Interactive agent hosts should follow the OAuth challenge returned by the MCP endpoint. Organization-owned server integrations can use a scoped GoFaceless API key. Send either credential only asAuthorization: Bearer <token>. Never place credentials in a URL, prompt, query string, webhook body, analytics property, or log.

OAuth authorization-server discovery is available at /.well-known/oauth-authorization-server. The MCP protected-resource document names the exact audience, authorization server, scopes, and header-based bearer method.

Use durable and retry-safe operations

Read video capabilities before choosing a tool or endpoint. Mutations require an Idempotency-Key; state-bound decisions also use the current state validator. Set X-GoFaceless-Mode: sandboxfor deterministic no-spend integration fixtures. The live mode still enforces product entitlements, customer cost authorization, credit ceilings, input rights, and current session state before consequential work begins.

curl https://api.gofaceless.ai/api/v1/video-sessions/capabilities \
  -H "Authorization: Bearer $GOFACELESS_TOKEN" \
  -H "GoFaceless-Version: 2026-07-26" \
  -H "X-GoFaceless-Mode: sandbox"

Let clients recover in real time

API responses expose the current calendar contract and API mode. Rate-limit responses use the current structured RateLimit fields and retain legacy X-RateLimit compatibility fields. A 429 includesRetry-After. Errors use application/problem+jsonwith a stable code, retryability, and recovery instruction.

Deprecated calendar contracts include Deprecation,Sunset, and a policy link on every response. Read the GoFaceless API versioning and deprecation policy before pinning a contract in production.

Integration entry points