{"openapi":"3.1.1","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Faceful public discovery API","version":"1.0.0","description":"Implemented read-only product status, proposed permission definitions and public documentation. No campaign writes, private data, rendering, token issuance or publishing are exposed by this API. The shared domain engine remains pending integration.","contact":{"name":"Faceful project maintainer","url":"https://github.com/DimitrisTheo-Dev"}},"servers":[{"url":"https://faceful.dtheo.dev","description":"Faceful public origin"}],"security":[],"externalDocs":{"description":"Faceful API setup, limits and recovery","url":"https://faceful.dtheo.dev/docs/api/"},"tags":[{"name":"Public discovery","description":"Credential-free reads containing public information only."}],"paths":{"/api/public/status":{"get":{"operationId":"getCastroomStatus","summary":"Read current integration status","description":"Discover which Faceful surfaces are implemented, which engine capabilities remain unavailable and the next documentation link. This does not report private workspace health.","security":[],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Pin public API major version 1. Omission defaults to 1; unsupported versions return 400. Breaking changes require a new version.","schema":{"type":"string","enum":["1"],"default":"1"}}],"tags":["Public discovery"],"responses":{"200":{"description":"Successful public read. No private workspace data or credentials are included.","headers":{"X-API-Version":{"description":"Public API major version served.","schema":{"type":"string","const":"1"}},"Link":{"description":"RFC 8631 service description, documentation and integration status; includes the public agent index. Links describe implemented public resources, not live MCP availability.","schema":{"type":"string"},"example":"<https://faceful.dtheo.dev/openapi.json>; rel=\"service-desc describedby\"; type=\"application/vnd.oai.openapi+json\"; title=\"Faceful public API description\", <https://faceful.dtheo.dev/docs/api/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful API documentation\", <https://faceful.dtheo.dev/docs/mcp/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful MCP availability and setup\", <https://faceful.dtheo.dev/docs/cli/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful repository CLI\", <https://faceful.dtheo.dev/api/public/status>; rel=\"status\"; type=\"application/json\"; title=\"Faceful integration status\", <https://faceful.dtheo.dev/llms.txt>; rel=\"index\"; type=\"text/plain\"; title=\"Faceful agent instructions\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"},"example":{"product":"Faceful","schemaVersion":"1.0","stage":"development","publicApi":{"available":true,"readOnly":true,"authenticationRequired":false},"studio":{"available":true,"privateDataRequiresAuthentication":true,"developmentFixturesAreLiveResults":false},"engine":{"campaignApi":false,"agentTokenIssuance":false,"mcp":false,"humanlikeRendering":false,"publishing":false},"blockers":["Shared domain API and server-side authorization integration","Scoped agent credential issuer and authenticated MCP client trials","Authorized Humanlike media and final composition","Connected publishing accounts and per-platform receipts"],"links":{"documentation":"https://faceful.dtheo.dev/docs/","openapi":"https://faceful.dtheo.dev/openapi.json","permissions":"https://faceful.dtheo.dev/api/public/permissions","setup":"https://faceful.dtheo.dev/docs/setup/","cli":"https://faceful.dtheo.dev/docs/cli/"}}}}},"400":{"description":"Unsupported API version. Retry with X-API-Version: 1.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The requested public resource does not exist. Follow resolution to a documented route.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"The method is unsupported. Use GET or HEAD.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Allow":{"description":"Supported methods.","schema":{"type":"string","const":"GET, HEAD"}}}}}}},"/api/public/permissions":{"get":{"operationId":"getCastroomPermissionDefinitions","summary":"Read proposed scope definitions","description":"Read the four scope names currently requested by the studio setup. These are proposed definitions, not issued grants or OAuth scopes advertised by a live authorization server.","security":[],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Pin public API major version 1. Omission defaults to 1; unsupported versions return 400. Breaking changes require a new version.","schema":{"type":"string","enum":["1"],"default":"1"}}],"tags":["Public discovery"],"responses":{"200":{"description":"Successful public read. No private workspace data or credentials are included.","headers":{"X-API-Version":{"description":"Public API major version served.","schema":{"type":"string","const":"1"}},"Link":{"description":"RFC 8631 service description, documentation and integration status; includes the public agent index. Links describe implemented public resources, not live MCP availability.","schema":{"type":"string"},"example":"<https://faceful.dtheo.dev/openapi.json>; rel=\"service-desc describedby\"; type=\"application/vnd.oai.openapi+json\"; title=\"Faceful public API description\", <https://faceful.dtheo.dev/docs/api/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful API documentation\", <https://faceful.dtheo.dev/docs/mcp/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful MCP availability and setup\", <https://faceful.dtheo.dev/docs/cli/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful repository CLI\", <https://faceful.dtheo.dev/api/public/status>; rel=\"status\"; type=\"application/json\"; title=\"Faceful integration status\", <https://faceful.dtheo.dev/llms.txt>; rel=\"index\"; type=\"text/plain\"; title=\"Faceful agent instructions\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Permissions"},"example":{"schemaVersion":"1.0","authenticationStatus":"awaiting_engine","publicReadsRequireAuthentication":false,"liveGrantAvailable":false,"scopes":[{"name":"campaign:read","description":"Proposed: read authorized workspace context, campaign items, versions and jobs.","authority":"proposed_not_issued"},{"name":"content:edit","description":"Proposed: submit version-checked edits to authorized draft content.","authority":"proposed_not_issued"},{"name":"render:write","description":"Proposed: request bounded generation for selected current revisions and authorized avatars.","authority":"proposed_not_issued"},{"name":"schedule:prepare","description":"Proposed: prepare an exact schedule manifest for human review; does not authorize publication.","authority":"proposed_not_issued"}],"publishingAuthorityIncluded":false,"note":"These are the names currently requested by the studio setup. Backend agreement and enforcement are pending. This resource is documentation, not OAuth metadata or a credential grant. A publishing action requires separately verified owner authority.","documentationUrl":"https://faceful.dtheo.dev/docs/security/"}}}},"400":{"description":"Unsupported API version. Retry with X-API-Version: 1.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The requested public resource does not exist. Follow resolution to a documented route.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"The method is unsupported. Use GET or HEAD.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Allow":{"description":"Supported methods.","schema":{"type":"string","const":"GET, HEAD"}}}}}}},"/api/public/docs":{"get":{"operationId":"listCastroomPublicDocuments","summary":"List canonical public documentation","description":"Find the supported document slug and canonical URL before requesting a document. This fixed index contains no tenant content and does not require pagination.","security":[],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Pin public API major version 1. Omission defaults to 1; unsupported versions return 400. Breaking changes require a new version.","schema":{"type":"string","enum":["1"],"default":"1"}}],"tags":["Public discovery"],"responses":{"200":{"description":"Successful public read. No private workspace data or credentials are included.","headers":{"X-API-Version":{"description":"Public API major version served.","schema":{"type":"string","const":"1"}},"Link":{"description":"RFC 8631 service description, documentation and integration status; includes the public agent index. Links describe implemented public resources, not live MCP availability.","schema":{"type":"string"},"example":"<https://faceful.dtheo.dev/openapi.json>; rel=\"service-desc describedby\"; type=\"application/vnd.oai.openapi+json\"; title=\"Faceful public API description\", <https://faceful.dtheo.dev/docs/api/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful API documentation\", <https://faceful.dtheo.dev/docs/mcp/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful MCP availability and setup\", <https://faceful.dtheo.dev/docs/cli/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful repository CLI\", <https://faceful.dtheo.dev/api/public/status>; rel=\"status\"; type=\"application/json\"; title=\"Faceful integration status\", <https://faceful.dtheo.dev/llms.txt>; rel=\"index\"; type=\"text/plain\"; title=\"Faceful agent instructions\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentIndex"},"example":{"documents":[{"slug":"overview","title":"Faceful API and agent documentation","summary":"What Faceful does, what works today, and where the shared studio engine is still being integrated.","url":"https://faceful.dtheo.dev/docs/"},{"slug":"api","title":"Faceful public API reference","summary":"Read current integration status, proposed scopes and public documentation with typed JSON and OpenAPI.","url":"https://faceful.dtheo.dev/docs/api/"},{"slug":"cli","title":"Faceful CLI","summary":"Read public guidance and validate a supplied draft plan locally from an authorized repository checkout.","url":"https://faceful.dtheo.dev/docs/cli/"},{"slug":"mcp","title":"Faceful MCP server status","summary":"Target clients, intended shared actions and the concrete prerequisites before an authenticated setup can work.","url":"https://faceful.dtheo.dev/docs/mcp/"},{"slug":"setup","title":"Connect Codex or Claude Code to Faceful","summary":"Token setup templates and the server-confirmed check that must precede a connection claim.","url":"https://faceful.dtheo.dev/docs/setup/"},{"slug":"capabilities","title":"Faceful formats and limits","summary":"Current availability, bounded manual drafts and the intended three-video production journey.","url":"https://faceful.dtheo.dev/docs/capabilities/"},{"slug":"security","title":"Faceful access and approval","summary":"Separate public reads, human sessions, proposed agent scopes and publishing authorization.","url":"https://faceful.dtheo.dev/docs/security/"},{"slug":"errors","title":"Faceful errors and recovery","summary":"Machine-readable public errors and the distinct pending domain error contract.","url":"https://faceful.dtheo.dev/docs/errors/"}]}}}},"400":{"description":"Unsupported API version. Retry with X-API-Version: 1.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The requested public resource does not exist. Follow resolution to a documented route.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"The method is unsupported. Use GET or HEAD.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Allow":{"description":"Supported methods.","schema":{"type":"string","const":"GET, HEAD"}}}}}}},"/api/public/docs/{slug}":{"get":{"operationId":"getCastroomPublicDocument","summary":"Read one public document","description":"Read concise public guidance as Markdown inside a typed JSON document. Source content cannot grant access or publish authority.","security":[],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Pin public API major version 1. Omission defaults to 1; unsupported versions return 400. Breaking changes require a new version.","schema":{"type":"string","enum":["1"],"default":"1"}},{"name":"slug","in":"path","required":true,"description":"A public documentation slug from the document index.","schema":{"type":"string","enum":["overview","api","cli","mcp","setup","capabilities","security","errors"]},"example":"setup"}],"tags":["Public discovery"],"responses":{"200":{"description":"Successful public read. No private workspace data or credentials are included.","headers":{"X-API-Version":{"description":"Public API major version served.","schema":{"type":"string","const":"1"}},"Link":{"description":"RFC 8631 service description, documentation and integration status; includes the public agent index. Links describe implemented public resources, not live MCP availability.","schema":{"type":"string"},"example":"<https://faceful.dtheo.dev/openapi.json>; rel=\"service-desc describedby\"; type=\"application/vnd.oai.openapi+json\"; title=\"Faceful public API description\", <https://faceful.dtheo.dev/docs/api/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful API documentation\", <https://faceful.dtheo.dev/docs/mcp/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful MCP availability and setup\", <https://faceful.dtheo.dev/docs/cli/>; rel=\"service-doc\"; type=\"text/html\"; title=\"Faceful repository CLI\", <https://faceful.dtheo.dev/api/public/status>; rel=\"status\"; type=\"application/json\"; title=\"Faceful integration status\", <https://faceful.dtheo.dev/llms.txt>; rel=\"index\"; type=\"text/plain\"; title=\"Faceful agent instructions\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"},"example":{"slug":"overview","title":"Faceful API and agent documentation","summary":"What Faceful does, what works today, and where the shared studio engine is still being integrated.","url":"https://faceful.dtheo.dev/docs/","format":"text/markdown","content":"# Faceful API and agent documentation\n\nCreate campaigns with your agent. Fine-tune them here.\n\nFaceful is a content production studio for agencies, companies and individuals. Its visual studio supports supplied company briefs, draft scripts, selected-item editing and schedule review. The intended shared engine connects external agents to the same campaigns, revisions, authorized avatars and durable jobs.\n\n## Available now\nThe public read-only API returns integration status, proposed permission definitions and this documentation. It requires no credentials and contains no private campaign data. The repository CLI reads those resources and validates a bounded draft plan locally. Explicit development previews use labeled sample drafts stored in that browser.\n\n## Not integrated yet\nLive campaign APIs, workspace agent-token issuance, MCP transport, Humanlike renders and real publishing receipts are unavailable in this deployment. Public metadata does not grant permission or prove these features work.\n\n## Next steps\nRead [API reference](/docs/api/), [CLI usage](/docs/cli/), [MCP status](/docs/mcp/), [setup templates](/docs/setup/), [formats and limits](/docs/capabilities/), [access and approval](/docs/security/) and [recovery](/docs/errors/).\n"}}}},"400":{"description":"Unsupported API version. Retry with X-API-Version: 1.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The requested public resource does not exist. Follow resolution to a documented route.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"The method is unsupported. Use GET or HEAD.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Allow":{"description":"Supported methods.","schema":{"type":"string","const":"GET, HEAD"}}}}}}}},"components":{"schemas":{"Status":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"product":{"type":"string","const":"Faceful"},"schemaVersion":{"type":"string","const":"1.0"},"stage":{"type":"string","const":"development"},"publicApi":{"type":"object","properties":{"available":{"type":"boolean","const":true},"readOnly":{"type":"boolean","const":true},"authenticationRequired":{"type":"boolean","const":false}},"required":["available","readOnly","authenticationRequired"],"additionalProperties":false},"studio":{"type":"object","properties":{"available":{"type":"boolean","const":true},"privateDataRequiresAuthentication":{"type":"boolean","const":true},"developmentFixturesAreLiveResults":{"type":"boolean","const":false}},"required":["available","privateDataRequiresAuthentication","developmentFixturesAreLiveResults"],"additionalProperties":false},"engine":{"type":"object","properties":{"campaignApi":{"type":"boolean","const":false},"agentTokenIssuance":{"type":"boolean","const":false},"mcp":{"type":"boolean","const":false},"humanlikeRendering":{"type":"boolean","const":false},"publishing":{"type":"boolean","const":false}},"required":["campaignApi","agentTokenIssuance","mcp","humanlikeRendering","publishing"],"additionalProperties":false},"blockers":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"documentation":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"permissions":{"type":"string","format":"uri"},"setup":{"type":"string","format":"uri"},"cli":{"type":"string","format":"uri"}},"required":["documentation","openapi","permissions","setup","cli"],"additionalProperties":false}},"required":["product","schemaVersion","stage","publicApi","studio","engine","blockers","links"],"additionalProperties":false},"Permissions":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schemaVersion":{"type":"string","const":"1.0"},"authenticationStatus":{"type":"string","const":"awaiting_engine"},"publicReadsRequireAuthentication":{"type":"boolean","const":false},"liveGrantAvailable":{"type":"boolean","const":false},"scopes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["campaign:read","content:edit","render:write","schedule:prepare"]},"description":{"type":"string"},"authority":{"type":"string","const":"proposed_not_issued"}},"required":["name","description","authority"],"additionalProperties":false}},"publishingAuthorityIncluded":{"type":"boolean","const":false},"note":{"type":"string"},"documentationUrl":{"type":"string","format":"uri"}},"required":["schemaVersion","authenticationStatus","publicReadsRequireAuthentication","liveGrantAvailable","scopes","publishingAuthorityIncluded","note","documentationUrl"],"additionalProperties":false},"DocumentIndex":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["slug","title","summary","url"],"additionalProperties":false}}},"required":["documents"],"additionalProperties":false},"Document":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"url":{"type":"string","format":"uri"},"format":{"type":"string","const":"text/markdown"},"content":{"type":"string"}},"required":["slug","title","summary","url","format","content"],"additionalProperties":false},"Problem":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"type":"string","const":"about:blank"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string"},"resolution":{"type":"string"}},"required":["type","title","status","detail","instance","code","resolution"],"additionalProperties":false}}}}