API Overview

The Faces API is a REST API that lets you programmatically generate and manage interactive, explorable decks. Pitches, portfolios, guides, and proposals. Describe what you want in a prompt, and Faces builds it.

Base URL

https://faces.app/api/v1

Authentication

Include your API key as a Bearer token:

Authorization: Bearer faces_your_key_here

See Authentication for how to create a key.

Request format

All request bodies are JSON (Content-Type: application/json)
All responses are JSON

Error responses

Errors return a JSON body with an error field and optionally a hint:

{
  "error": "prompt is required",
  "hint": "POST /api/v1/projects/generate {\"prompt\": \"<text>\"}"
}

Status	Meaning
`400`	Invalid request body or parameters
`401`	Missing or invalid API key
`402`	Insufficient credits to start a generation
`403`	Action requires a paid plan
`404`	Resource not found
`409`	Conflict (URL, subdomain, or domain already in use)
`429`	Rate limit exceeded (50 req/min)
`500`	Internal server error
`502`	Generation could not be dispatched

Rate limits

All endpoints share a 50 requests per minute limit per user. When exceeded:

Response status: 429
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Pagination

List endpoints use cursor-based pagination:

# First page
GET /projects?limit=10

# Next page (use nextCursor from previous response)
GET /projects?limit=10&cursor=cm1abc123...

API Reference

CLI

MCP

Base URL

Authentication

Request format

Error responses

Rate limits

​Base URL

​Authentication

​Request format

​Error responses

​Rate limits

​Pagination

Base URL

Authentication

Request format

Error responses

Rate limits

Pagination