openapi: "3.1.0"
info:
  title: "PlatPhorm News Onboard API"
  description: "API for the PlatPhorm News Network onboarding portal. Submit applications to join the creator network."
  version: "1.0.0"
  contact:
    name: "PlatPhorm News"
    url: "https://platphormnews.com"
  license:
    name: "MIT"
    url: "https://opensource.org/licenses/MIT"
servers:
  - 
    url: "https://onboard.platphormnews.com"
    description: "Production"
  - 
    url: "http://localhost:3000"
    description: "Development"
components:
  securitySchemes:
    PlatPhormBearer:
      type: "http"
      scheme: "bearer"
      description: "Use PLATPHORM_API_KEY for protected actions"
    PlatPhormHeader:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Use PLATPHORM_API_KEY for protected actions"
paths:
  /health:
    get:
      summary: "Health Check"
      description: "Alias for /api/health when reading this document under /api/docs"
      operationId: "getApiHealthAlias"
      tags:
        - System
      responses:
        200:
          description: "Health payload"
  /api/health:
    get:
      summary: "Health Check"
      description: "Returns the health status of the API"
      operationId: "getHealth"
      tags:
        - System
      responses:
        200:
          description: "Healthy response"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: "string"
                    example: "healthy"
                  version:
                    type: "string"
                    example: "1.0.0"
                  timestamp:
                    type: "string"
                    format: "date-time"
                  uptime:
                    type: "number"
                  service:
                    type: "string"
                  environment:
                    type: "string"
  /api/applications:
    post:
      summary: "Submit Application"
      description: "Submit a new application to join the PlatPhorm News Network"
      operationId: "submitApplication"
      tags:
        - Applications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              required:
                - publicUrl
                - creatorTypes
                - requestedSubdomain
                - email
              properties:
                publicUrl:
                  type: "string"
                  format: "uri"
                  description: "Public URL to the creator's work"
                  example: "https://etsy.com/shop/example"
                creatorTypes:
                  type: "array"
                  items:
                    type: "string"
                    enum:
                      - maker
                      - developer
                      - artist
                      - writer
                      - musician
                      - videographer
                      - designer
                      - educator
                      - entrepreneur
                      - photographer
                      - other
                  description: "One or more creator types"
                requestedSubdomain:
                  type: "string"
                  minLength: 3
                  pattern: "^[a-z0-9-]+$"
                  description: "Requested subdomain (yourname.platphormnews.com)"
                  example: "myshop"
                email:
                  type: "string"
                  format: "email"
                  description: "Contact email address"
                description:
                  type: "string"
                  description: "Optional additional details"
      responses:
        201:
          description: "Application submitted successfully"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  id:
                    type: "string"
                    example: "app_1710288000000_abc12345"
                  success:
                    type: "boolean"
                    example: true
                  siteId:
                    type: "string"
                    example: "app_1710288000000_abc12345"
                  domain:
                    type: "string"
                    example: "myshop.platphormnews.com"
                  trackingUrl:
                    type: "string"
                    format: "uri"
                  message:
                    type: "string"
                  steps:
                    type: "array"
                    items:
                      type: "object"
        400:
          description: "Invalid request"
        429:
          description: "Rate limit exceeded"
  /api/applications/{id}:
    get:
      summary: "Get Application Status"
      description: "Get application onboarding status by ID"
      operationId: "getApplicationStatus"
      tags:
        - Applications
      parameters:
        - 
          name: "id"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Application ID"
      responses:
        200:
          description: "Application status"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  id:
                    type: "string"
                  status:
                    type: "string"
                    enum:
                      - pending
                      - processing
                      - deployed
                      - failed
                  domain:
                    type: "string"
                  createdAt:
                    type: "string"
                    format: "date-time"
                  steps:
                    type: "array"
                    items:
                      type: "object"
                  siteUrl:
                    type: "string"
                  repoUrl:
                    type: "string"
                  dashboardUrl:
                    type: "string"
        404:
          description: "Application not found"
  /api/url-preview:
    get:
      summary: "URL Preview"
      description: "Fetch Open Graph metadata for a URL"
      operationId: "getUrlPreview"
      tags:
        - Utilities
      parameters:
        - 
          name: "url"
          in: "query"
          required: true
          schema:
            type: "string"
            format: "uri"
          description: "URL to fetch preview for"
      responses:
        200:
          description: "URL preview data"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  valid:
                    type: "boolean"
                  url:
                    type: "string"
                  title:
                    type: "string"
                  description:
                    type: "string"
                  image:
                    type: "string"
  /api/check-subdomain:
    get:
      summary: "Check Subdomain Availability"
      description: "Check if a subdomain is available"
      operationId: "checkSubdomain"
      tags:
        - Utilities
      parameters:
        - 
          name: "subdomain"
          in: "query"
          required: true
          schema:
            type: "string"
            minLength: 3
          description: "Subdomain to check"
      responses:
        200:
          description: "Availability status"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  subdomain:
                    type: "string"
                  available:
                    type: "boolean"
  /api/integrations:
    get:
      summary: "List Onboard integration status"
      description: "Returns public-safe readiness/degraded status for GitHub, Vercel, v0, Jules, Docs, Trace, BrowserOps, and Evals integrations."
      operationId: "listIntegrations"
      tags:
        - Integrations
      responses:
        200:
          description: "Integration status registry"
    post:
      summary: "Mutate integration registry"
      description: "Protected placeholder for future registry persistence. Requires PLATPHORM_API_KEY and currently returns degraded until persistence is configured."
      operationId: "mutateIntegrations"
      tags:
        - Integrations
      security:
        - 
          PlatPhormBearer:

        - 
          PlatPhormHeader:

      responses:
        401:
          description: "Missing PLATPHORM_API_KEY"
        503:
          description: "Persistence unavailable"
tags:
  - 
    name: "System"
    description: "System health and status endpoints"
  - 
    name: "Applications"
    description: "Application submission endpoints"
  - 
    name: "Utilities"
    description: "Helper utilities"
  - 
    name: "Integrations"
    description: "Cross-site and provider integration status"