openapi: "3.0.3"
info:
  title: "Jules PlatPhormNews API"
  version: "0.1.0"
  description: "Canonical AI coding-session workspace, repo-assistance, issue triage, onboarding-to-code handoff, prompt-to-task, MCP/API tool execution, and developer workflow assistant for the PlatPhormNews web mesh."
servers:
  - 
    url: "https://jules.platphormnews.com"
    description: "Production"
tags:
  - 
    name: "Sessions"
    description: "Coding-session workspace APIs"
  - 
    name: "Onboard"
    description: "Onboard-to-implementation handoff APIs"
  - 
    name: "Integrations"
    description: "Cross-site coding workflow integrations"
  - 
    name: "MCP"
    description: "MCP JSON-RPC and discovery"
  - 
    name: "Discovery"
    description: "Public discovery files"
paths:
  /api/health:
    get:
      summary: "Platform health payload."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/health:
    get:
      summary: "Versioned platform health payload."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/docs:
    get:
      summary: "OpenAPI JSON specification."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /openapi.yaml:
    get:
      summary: "OpenAPI YAML specification."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /.well-known/mcp.json:
    get:
      summary: "MCP discovery manifest."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /.well-known/agents.json:
    get:
      summary: "Agent discovery manifest."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /.well-known/ai-plugin.json:
    get:
      summary: "AI plugin manifest."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /.well-known/security.txt:
    get:
      summary: "Security contact."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /.well-known/trust.json:
    get:
      summary: "Trust policy."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/mcp:
    get:
      summary: "MCP metadata and usage."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    post:
      summary: "JSON-RPC MCP endpoint for public introspection and public-safe Jules handoff tools."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1alpha/auth-status:
    get:
      summary: "Public Google Jules provider status; does not expose JULES_API_KEY."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1alpha/sources:
    get:
      summary: "Public wrapper for connected Google Jules repository sources."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1alpha/sessions:
    get:
      summary: "Public wrapper for Google Jules session list using server-side JULES_API_KEY."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    post:
      summary: "Public wrapper to create a Google Jules coding session with the configured account."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1alpha/sessions/{id}:
    get:
      summary: "Public wrapper for Google Jules session detail."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    delete:
      summary: "Public wrapper for Google Jules session deletion through the configured account."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1alpha/sessions/{id}/activities:
    get:
      summary: "Public wrapper for Google Jules activity feed."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1alpha/sessions/{id}:sendMessage:
    post:
      summary: "Public wrapper to send follow-up feedback to a Google Jules session."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1alpha/sessions/{id}:approvePlan:
    post:
      summary: "Public wrapper to approve a Google Jules plan."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/github/auth-status:
    get:
      summary: "Public server-side GitHub credential status."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/github/repositories:
    get:
      summary: "List repositories available to the configured server-side GitHub account."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    post:
      summary: "List repositories with optional owner filter."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/github/repositories/create:
    post:
      summary: "Create a repository under the configured GitHub account or organization."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/sessions:
    get:
      summary: "List public-safe sessions; protected callers see private server sessions."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    post:
      summary: "Create protected server-side Jules session."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
  /api/v1/sessions/{id}:
    get:
      summary: "Get public-safe or protected session details."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    put:
      summary: "Update protected server-side session."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
    delete:
      summary: "Delete protected server-side session."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
  /api/v1/sessions/{id}/export:
    post:
      summary: "Export a session as JSON or Markdown."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
  /api/v1/sessions/import:
    post:
      summary: "Import session JSON."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
  /api/v1/sessions/{id}/messages:
    get:
      summary: "List public-safe messages or protected session messages."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    post:
      summary: "Add protected session message."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
  /api/v1/sessions/{id}/plans:
    get:
      summary: "List public-safe plans or protected session plans."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
    post:
      summary: "Generate implementation plan and task breakdown."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
  /api/v1/plans/{id}:
    get:
      summary: "Get plan details."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/onboard/applications:
    get:
      summary: "List public-safe Onboard availability and local imports."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/onboard/applications/{id}:
    get:
      summary: "Get public-safe Onboard application/import status."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/onboard/import:
    post:
      summary: "Import manually provided public-safe Onboard handoff data."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/onboard/import/{id}/create-session:
    post:
      summary: "Create public-safe Jules session from Onboard import."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/onboard/import/{id}/generate-plan:
    post:
      summary: "Generate public-safe plan from Onboard import."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/onboard/import/{id}/create-kanban-tasks:
    post:
      summary: "Create public Kanban task handoff from Onboard import."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/onboard/import/{id}/generate-docs:
    post:
      summary: "Create public Docs report handoff from Onboard import."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations:
    get:
      summary: "List Jules integration catalog."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations/status:
    get:
      summary: "Integration status, with optional live checks."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations/mcp/sync:
    post:
      summary: "Create public MCP registry sync handoff."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations/kanban/create-tasks:
    post:
      summary: "Create public Kanban task handoff."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations/docs/report:
    post:
      summary: "Create public Docs report handoff."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations/sandbox/dry-run:
    post:
      summary: "Create public Sandbox dry-run handoff."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations/browserops/run:
    post:
      summary: "Create public BrowserOps run handoff."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/integrations/evals/run:
    post:
      summary: "Create public Evals run handoff."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/network/graph:
    get:
      summary: "Read root network graph with degraded status."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/network/graph/sync:
    post:
      summary: "Protected graph sync."
      security:
        - 
          PlatPhormApiKey:
[]
        - 
          PlatPhormBearer:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
        401:
          description: "PLATPHORM_API_KEY required."
        403:
          description: "PLATPHORM_API_KEY rejected."
  /api/v1/network/sites:
    get:
      summary: "Discovered site list."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/network/trusted-domains:
    get:
      summary: "Trusted domain policy."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/network/route-compliance:
    get:
      summary: "Route compliance summary."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
  /api/v1/network/discovery-compliance:
    get:
      summary: "Discovery compliance summary."
      security:
[]
      responses:
        200:
          description: "Successful response using { ok: true, data } where applicable."
components:
  securitySchemes:
    PlatPhormApiKey:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Set to PLATPHORM_API_KEY for protected Jules actions."
    PlatPhormBearer:
      type: "http"
      scheme: "bearer"
      description: "Authorization: Bearer $PLATPHORM_API_KEY"