Faceful API documentation
Discover current capabilities and public guidance with typed, credential-free reads.
The public discovery API gives agents an honest starting point: integration status, proposed permission definitions and documentation. It cannot read private campaigns, issue credentials, create videos or publish posts.
The OpenAPI 3.1.1 document describes only the implemented public routes. Authentication and shared campaign operations require Minas’s engine integration and separate live verification.
Make the first call
curl --fail-with-body -sS -H 'Accept: application/json' \
https://faceful.dtheo.dev/api/public/statusThese reads require no token. Never send Supabase keys, browser cookies or downstream provider tokens to the public API.
Implemented operations
| Path | Result |
|---|---|
/api/public/status | Implemented surfaces, unavailable engine capabilities and useful links. |
/api/public/permissions | Four proposed scope definitions. They are not active grants or OAuth metadata. |
/api/public/docs | Fixed documentation index with supported slugs and canonical URLs. |
/api/public/docs/{slug} | One document as Markdown content inside typed JSON. |
Each operation has a unique operation ID, a description, response schemas and a concrete example in the specification. There is no arbitrary URL-fetch operation. HEAD has the same status and headers as GET, without a response body.
Versioning and deprecation
Send X-API-Version: 1 to pin major version 1. Omission defaults to 1. JSON responses identify the served version and include Vary: X-API-Version. An unsupported version returns HTTP 400 with unsupported_api_version. The repository CLI pins version 1.
Additive fields may be introduced within a major version; incompatible changes require a new version. Before retiring a version, we will publish its migration path here and emit the Deprecation header and a Link with rel=deprecation. A Sunset header will identify a confirmed retirement date. No version is currently deprecated and no sunset is announced, so those headers are not emitted.
Errors and recovery
Unknown public routes return HTTP 404. Unsupported methods on known routes return HTTP 405 and Allow: GET, HEAD. Both use RFC 9457 application/problem+json with a stable code and actionable resolution.
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "This public document is not available.",
"instance": "/api/public/docs/missing",
"code": "document_not_found",
"resolution": "Read /api/public/docs for supported document slugs, or visit /docs/."
}Limits and caching
The documentation index is finite and needs no pagination. Successful public reads may be cached for 60 seconds; errors are not cached. Hosting limits remain subject to the deployment platform. No numeric production quota or dollar budget is advertised before it is enforced by the engine. Avoid aggressive polling and honor any platform retry response.
Next step
Use the repository CLI for public discovery and local plan validation. Read MCP integration status before attempting a client setup. A valid local plan is not an accepted render or an authorized schedule.