Skip to main content
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>\"}"
}
StatusMeaning
400Invalid request body or parameters
401Missing or invalid API key
404Resource not found
429Rate limit exceeded (50 req/min)
500Internal server error

​
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...