{ "openapi": "3.1.0", "info": { "title": "Launchfiles Interoperability API", "version": "0.1.0", "description": "V0 draft contract for Launchfiles agentic economy interoperability. Public OpenAPI is discovery metadata, not execution authority. Most /api/v0 mutation routes are planned only. Scoped production challenge execution is available only from the authenticated challenge manifest.\n\nOptional mission capacities include page repair packages, design-system checks, and no-publish landing briefs. Empty GSC volume is never invented. Not an autonomous page builder or publisher.", "contact": { "url": "https://launchfiles.app" }, "license": { "name": "Proprietary", "url": "https://launchfiles.app/agents" } }, "servers": [ { "url": "https://launchfiles.app", "description": "Public contract origin. Discovery GET surfaces are public; /api/v0 operations are planned; challenge execution endpoints are disclosed by the authenticated manifest only." } ], "tags": [ { "name": "Discovery", "description": "Public agent-readable discovery surfaces" }, { "name": "Challenge", "description": "Authenticated production challenge manifest metadata" }, { "name": "Objects", "description": "Launchfile object read APIs (planned)" }, { "name": "Missions", "description": "Mission planning APIs (planned)" }, { "name": "Agent Actions", "description": "Bounded agent propose/approval/execution APIs (planned)" }, { "name": "Receipts", "description": "Durable receipt recording (planned)" }, { "name": "Readouts", "description": "Outcome measurement APIs (planned)" } ], "paths": { "/.well-known/launchfiles.json": { "get": { "tags": [ "Discovery" ], "summary": "Launchfiles discovery manifest", "operationId": "getWellKnownManifest", "x-launchfiles-exposure-boundary": "public_discovery", "x-launchfiles-status": "live_discovery", "responses": { "200": { "description": "Discovery manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WellKnownManifest" } } } } } } }, "/.well-known/launchfiles-agent.json": { "get": { "tags": [ "Discovery" ], "summary": "Launchfiles agent discovery manifest alias", "operationId": "getWellKnownAgentManifest", "x-launchfiles-exposure-boundary": "public_discovery", "x-launchfiles-status": "live_discovery", "responses": { "200": { "description": "Compatible discovery manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WellKnownManifest" } } } } } } }, "/llms.txt": { "get": { "tags": [ "Discovery" ], "summary": "Agent-readable product map", "operationId": "getLlmsTxt", "x-launchfiles-exposure-boundary": "public_discovery", "x-launchfiles-status": "live_discovery", "responses": { "200": { "description": "Plain-text agent product map", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/agents": { "get": { "tags": [ "Discovery" ], "summary": "Agent operating contract page", "operationId": "getAgentsPage", "x-launchfiles-exposure-boundary": "public_discovery", "x-launchfiles-status": "live_discovery", "responses": { "200": { "description": "HTML agent contract page", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Discovery" ], "summary": "OpenAPI contract draft", "operationId": "getOpenApi", "x-launchfiles-exposure-boundary": "public_discovery", "x-launchfiles-status": "live_discovery", "responses": { "200": { "description": "This OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/founder/prod-challenge-manifest": { "get": { "tags": [ "Challenge" ], "summary": "Authenticated production challenge manifest", "description": "Live authenticated metadata. Requires a founder session or scoped challenge token. This manifest, not public OpenAPI, lists the exact callable production challenge endpoints for prefixed prod_program_suite_* products.", "operationId": "getProdChallengeManifest", "x-launchfiles-status": "live_authenticated_manifest", "x-launchfiles-exposure-boundary": "customer_workspace_readonly", "security": [ { "prodChallengeBearer": [] }, { "founderSessionCookie": [] } ], "responses": { "200": { "description": "Scoped challenge manifest with allowed endpoints, scopes, polling policy, cleanup semantics, and receipt truth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProdChallengeManifest" } } } }, "401": { "$ref": "#/components/responses/AuthRequired" }, "403": { "$ref": "#/components/responses/AuthRequired" } } } }, "/api/v0/objects/{objectId}": { "get": { "tags": [ "Objects" ], "summary": "Get a launchfile object by ID", "description": "Planned \u2014 not implemented in V0.", "operationId": "getObject", "x-launchfiles-status": "planned", "x-launchfiles-exposure-boundary": "customer_workspace_readonly", "security": [ { "launchfilesOAuth": [ "launchfiles:read" ] } ], "parameters": [ { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "501": { "$ref": "#/components/responses/NotImplemented" }, "200": { "description": "Launchfile object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchfileObjectEnvelope" } } } } } } }, "/api/v0/missions/{missionId}": { "get": { "tags": [ "Missions" ], "summary": "Get a mission by ID", "description": "Planned \u2014 not implemented in V0. Requires future workspace auth.", "operationId": "getMission", "x-launchfiles-status": "planned", "x-launchfiles-exposure-boundary": "customer_workspace_readonly", "security": [ { "launchfilesOAuth": [ "launchfiles:read" ] } ], "parameters": [ { "name": "missionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "501": { "$ref": "#/components/responses/NotImplemented" }, "200": { "description": "Planned mission object response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MissionEnvelope" } } } } } } }, "/api/v0/missions/plan": { "post": { "tags": [ "Missions" ], "summary": "Plan a website or search expansion mission", "description": "Planned \u2014 not implemented in V0. Requires launchfiles:plan_mission scope and produces a proposal, not execution.", "operationId": "planMission", "x-launchfiles-status": "planned", "x-launchfiles-exposure-boundary": "customer_workspace_proposed", "security": [ { "launchfilesOAuth": [ "launchfiles:plan_mission" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebsiteMissionPlanRequest" }, { "$ref": "#/components/schemas/SearchExpansionMissionPlanRequest" } ] } } } }, "responses": { "501": { "$ref": "#/components/responses/NotImplemented" }, "202": { "description": "Planned mission-plan proposal response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalAcknowledgement" } } } } } } }, "/api/v0/agent-actions/propose": { "post": { "tags": [ "Agent Actions" ], "summary": "Propose a bounded agent action", "description": "Planned \u2014 not implemented in V0. Proposals are not approvals or execution.", "operationId": "proposeAgentAction", "x-launchfiles-status": "planned", "x-launchfiles-exposure-boundary": "customer_workspace_proposed", "security": [ { "launchfilesOAuth": [ "launchfiles:propose" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentActionRequest" } } } }, "responses": { "501": { "$ref": "#/components/responses/NotImplemented" }, "202": { "description": "Planned bounded-action proposal response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalAcknowledgement" } } } } } } }, "/api/v0/agent-actions/request-approval": { "post": { "tags": [ "Agent Actions" ], "summary": "Request founder approval for a scoped action", "description": "Planned \u2014 not implemented in V0.", "operationId": "requestAgentApproval", "x-launchfiles-status": "planned", "x-launchfiles-exposure-boundary": "customer_workspace_proposed", "security": [ { "launchfilesOAuth": [ "launchfiles:request_approval" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentActionRequest" } } } }, "responses": { "501": { "$ref": "#/components/responses/NotImplemented" }, "202": { "description": "Planned approval-request acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequestAcknowledgement" } } } } } } }, "/api/v0/receipts": { "post": { "tags": [ "Receipts" ], "summary": "Record a durable action receipt", "description": "Planned \u2014 not implemented in V0. Requires launchfiles:record_receipt and linked work order.", "operationId": "recordReceipt", "x-launchfiles-status": "planned", "x-launchfiles-exposure-boundary": "future_external_planned", "security": [ { "launchfilesOAuth": [ "launchfiles:record_receipt" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentActionReceipt" } } } }, "responses": { "501": { "$ref": "#/components/responses/NotImplemented" }, "201": { "description": "Planned durable receipt response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentActionReceipt" } } } } } } }, "/api/v0/readouts/{readoutId}": { "get": { "tags": [ "Readouts" ], "summary": "Get a readout by ID", "description": "Planned \u2014 not implemented in V0.", "operationId": "getReadout", "x-launchfiles-status": "planned", "x-launchfiles-exposure-boundary": "customer_workspace_readonly", "security": [ { "launchfilesOAuth": [ "launchfiles:read" ] } ], "parameters": [ { "name": "readoutId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "501": { "$ref": "#/components/responses/NotImplemented" }, "200": { "description": "Planned readout response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadoutEnvelope" } } } } } } } }, "components": { "securitySchemes": { "launchfilesOAuth": { "type": "oauth2", "description": "Draft OAuth/OIDC-style scope model. Not wired in V0.", "flows": { "authorizationCode": { "authorizationUrl": "https://launchfiles.app/oauth/authorize", "tokenUrl": "https://launchfiles.app/oauth/token", "scopes": { "launchfiles:read": "Read approved context and public objects", "launchfiles:propose": "Propose bounded work objects", "launchfiles:request_approval": "Request founder approval", "launchfiles:record_receipt": "Record durable receipts", "launchfiles:plan_mission": "Plan website or search expansion missions", "launchfiles:execute_with_approval": "Execute exact approved work with receipt", "launchfiles:admin": "Administrative scope (not granted to external agents in V0)" } } } }, "prodChallengeBearer": { "type": "http", "scheme": "bearer", "description": "Founder-issued scoped challenge token. Send Authorization: Bearer . Valid only for prod_program_suite_* challenge products and mission run/retrieve." }, "founderSessionCookie": { "type": "apiKey", "in": "cookie", "name": "launchfiles_founder_session", "description": "Signed founder session cookie. Used by the founder UI and manifest access; not an external-agent bearer token." } }, "responses": { "AuthRequired": { "description": "Founder session or scoped challenge token required", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error", "next_action" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "next_action": { "type": "string" } } } } } }, "NotImplemented": { "description": "Route defined in contract only \u2014 not implemented in V0", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "status" ], "properties": { "error": { "type": "string", "const": "not_implemented" }, "status": { "type": "string", "const": "planned" }, "message": { "type": "string" } } } } } } }, "schemas": { "WellKnownManifest": { "type": "object", "required": [ "name", "domain", "description", "object", "version", "status", "publicSurfaces", "capabilities", "unsupported" ], "properties": { "name": { "type": "string", "const": "Launchfiles" }, "domain": { "type": "string", "const": "launchfiles.app" }, "description": { "type": "string" }, "object": { "type": "string", "const": "launchfile" }, "version": { "type": "string" }, "status": { "type": "string", "enum": [ "beta", "alpha", "production" ] }, "publicSurfaces": { "type": "object", "properties": { "llms": { "type": "string" }, "agents": { "type": "string" }, "openapi": { "type": "string" }, "wellKnown": { "type": "string" }, "wellKnownAgent": { "type": "string" } } }, "authenticatedSurfaces": { "type": "object", "properties": { "challengeManifest": { "type": "string" } } }, "challengeExecution": { "type": "object", "properties": { "status": { "type": "string" }, "manifest": { "type": "string" }, "allowedProductPrefix": { "type": "string", "const": "prod_program_suite_" }, "publicOpenApiIsExecutionAuthority": { "type": "boolean", "const": false }, "repoAccessRequired": { "type": "boolean", "const": false } } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "unsupported": { "type": "array", "items": { "type": "string" } }, "contact": { "type": "object", "properties": { "website": { "type": "string", "format": "uri" } } }, "schemaRegistryStatus": { "type": "string", "const": "planned_not_public" } } }, "ProdChallengeManifest": { "type": "object", "required": [ "schema_version", "base_url", "mode", "token_status", "allowed_product_prefix", "allowed_scopes", "forbidden", "endpoints", "product_families", "request_examples", "polling_policy", "receipt_truth" ], "properties": { "schema_version": { "type": "string", "const": "launchfiles_prod_challenge_manifest_v1" }, "base_url": { "type": "string", "format": "uri" }, "mode": { "type": "string", "const": "production_no_publish" }, "token_status": { "type": "string", "const": "valid" }, "allowed_product_prefix": { "type": "string", "const": "prod_program_suite_" }, "allowed_scopes": { "type": "array", "items": { "type": "string", "enum": [ "product:create", "product:read", "product:delete", "mission:run", "mission:retrieve" ] } }, "forbidden": { "type": "array", "items": { "type": "string" } }, "endpoints": { "type": "object", "additionalProperties": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "required_scope": { "type": "string" } } } }, "product_families": { "type": "array", "items": { "type": "object" } }, "request_examples": { "type": "object" }, "polling_policy": { "type": "object" }, "receipt_truth": { "type": "object" } } }, "LaunchfileObjectEnvelope": { "type": "object", "required": [ "schemaVersion", "objectType", "objectId", "workspaceId" ], "properties": { "schemaVersion": { "type": "string", "const": "launchfile_object_v0" }, "objectType": { "type": "string" }, "objectId": { "type": "string" }, "workspaceId": { "type": "string" }, "payload": { "type": "object" } } }, "WebsiteMissionPlanRequest": { "type": "object", "required": [ "workspaceId", "mode", "sourceEnvironment" ], "properties": { "workspaceId": { "type": "string" }, "mode": { "type": "string", "enum": [ "build_new_page", "audit_existing_page", "create_page_spec", "repair_page", "compare_page_versions", "optimize_live_page", "rendered_qa_only" ] }, "sourceEnvironment": { "type": "string" } } }, "SearchExpansionMissionPlanRequest": { "type": "object", "required": [ "workspaceId", "propertyName" ], "properties": { "workspaceId": { "type": "string" }, "propertyName": { "type": "string" }, "signalOnly": { "type": "boolean" } } }, "AgentActionRequest": { "$comment": "See packages/core/schemas/agent_action_request.schema.json", "type": "object", "required": [ "schemaVersion", "requestId", "workspaceId", "agentId", "requestedAction", "scopeName", "workOrderId", "approvalScope", "idempotencyKey", "declaredSideEffects", "traceId", "sourceMode", "createdAt" ], "properties": { "schemaVersion": { "type": "string", "const": "launchfile_agent_v0" }, "requestId": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "requestedAction": { "type": "string" }, "scopeName": { "type": "string" }, "workOrderId": { "type": "string" }, "approvalScope": { "type": "object" }, "idempotencyKey": { "type": "string" }, "declaredSideEffects": { "type": "object" }, "traceId": { "type": "string", "pattern": "^(?!0{32})[0-9a-f]{32}$" }, "sourceMode": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "AgentActionReceipt": { "$comment": "See packages/core/schemas/agent_action_receipt.schema.json", "type": "object", "required": [ "schemaVersion", "receiptId", "requestId", "workspaceId", "agentId", "workOrderId", "scopeName", "terminalState", "sideEffectStatus", "traceId", "recordedAt", "createdAt" ], "properties": { "schemaVersion": { "type": "string", "const": "launchfile_agent_v0" }, "receiptId": { "type": "string" }, "requestId": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "workOrderId": { "type": "string" }, "scopeName": { "type": "string" }, "terminalState": { "type": "string" }, "sideEffectStatus": { "type": "string" }, "traceId": { "type": "string", "pattern": "^(?!0{32})[0-9a-f]{32}$" }, "recordedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "MissionEnvelope": { "type": "object", "required": [ "schemaVersion", "missionId", "workspaceId", "status" ], "additionalProperties": false, "properties": { "schemaVersion": { "type": "string", "const": "launchfile_object_v0" }, "missionId": { "type": "string" }, "workspaceId": { "type": "string" }, "status": { "type": "string" }, "missionType": { "type": "string", "enum": [ "website_mission", "search_expansion_mission" ] } } }, "ProposalAcknowledgement": { "type": "object", "required": [ "proposalId", "status", "traceId" ], "additionalProperties": false, "properties": { "proposalId": { "type": "string" }, "status": { "type": "string", "const": "proposed" }, "traceId": { "type": "string", "pattern": "^(?!0{32})[0-9a-f]{32}$" } } }, "ApprovalRequestAcknowledgement": { "type": "object", "required": [ "requestId", "status", "traceId" ], "additionalProperties": false, "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "const": "pending" }, "traceId": { "type": "string", "pattern": "^(?!0{32})[0-9a-f]{32}$" } } }, "ReadoutEnvelope": { "type": "object", "required": [ "schemaVersion", "readoutId", "workspaceId", "status" ], "additionalProperties": false, "properties": { "schemaVersion": { "type": "string", "const": "launchfile_object_v0" }, "readoutId": { "type": "string" }, "workspaceId": { "type": "string" }, "status": { "type": "string" } } } } } }