openapi: "3.1.0"
info:
  title: "PlatPhorm AgentUI"
  version: "0.1.0"
  description: "AgentUI API for human and agent interface artifacts: workflow orchestration, schema-to-form rendering, local/export/share/delegation packets, storage truth, templates, approvals, publishing boundaries, observability, and MCP JSON-RPC."
servers:
  - url: "https://agentui.platphormnews.com"
components:
  securitySchemes:
    PlatphormApiKeyBearer:
      type: "http"
      scheme: "bearer"
      bearerFormat: "PLATPHORM_API_KEY"
      description: "Use Authorization: Bearer $PLATPHORM_API_KEY"
    PlatphormApiKeyHeader:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Use X-PlatPhorm-API-Key: $PLATPHORM_API_KEY"
paths:
  /api/docs:
    get:
      summary: "OpenAPI JSON document"
  /api/health:
    get:
      summary: "Service health"
  /openapi.json:
    get:
      summary: "OpenAPI JSON document route"
  /openapi.yaml:
    get:
      summary: "OpenAPI YAML document route"
  /asyncapi.yaml:
    get:
      summary: "AsyncAPI YAML event contract for AgentUI workflow, run, approval, artifact, delegation, and integration events"
  /llms.txt:
    get:
      summary: "Concise AgentUI llms discovery text"
  /llms-full.txt:
    get:
      summary: "Full AgentUI llms discovery text"
  /llms-index.json:
    get:
      summary: "AgentUI llms discovery index"
  /rss.xml:
    get:
      summary: "Public-safe RSS feed"
  /feed.xml:
    get:
      summary: "Public-safe Atom feed"
  /sitemap.xml:
    get:
      summary: "Public sitemap"
  /sitemap-index.xml:
    get:
      summary: "Public sitemap index"
  /robots.txt:
    get:
      summary: "Robots policy"
  /manifest.webmanifest:
    get:
      summary: "Web app manifest"
  /.well-known/mcp.json:
    get:
      summary: "MCP well-known manifest"
  /.well-known/web4.json:
    get:
      summary: "AgentUI Web4 manifest"
  /.well-known/provenance.json:
    get:
      summary: "Public-safe provenance and fingerprint index"
  /.well-known/agents.json:
    get:
      summary: "Agent access well-known manifest"
  /.well-known/agent-policy.json:
    get:
      summary: "Agent policy manifest"
  /.well-known/ai-policy.json:
    get:
      summary: "AI policy manifest"
  /.well-known/security.txt:
    get:
      summary: "Security contact policy"
  /.well-known/trust.json:
    get:
      summary: "Trust and public/protected boundary policy"
  /api/mcp:
    get:
      summary: "MCP manifest and usage metadata"
      operationId: "getMcpManifest"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
    post:
      summary: "MCP JSON-RPC 2.0 transport"
      operationId: "postMcpJsonRpc"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                jsonrpc:
                  type: "string"
                  enum:
                    - "2.0"
                id:
                  oneOf:
                    - type: "string"
                    - type: "number"
                    - type: "null"
                method:
                  type: "string"
                  examples:
                    - "tools/list"
                    - "tools/call"
                params:
                  type: "object"
              required:
                - "jsonrpc"
                - "method"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/api-keys:
    get:
      summary: "List protected API-key inventory"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
    post:
      summary: "Create protected API key"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/approvals:
    get:
      summary: "List public-safe workflow approvals"
    post:
      summary: "Create workflow approval request"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/approvals/{id}:
    get:
      summary: "Get public-safe workflow approval"
  /api/v1/approvals/{id}/approve:
    post:
      summary: "Approve workflow approval step"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/approvals/{id}/reject:
    post:
      summary: "Reject workflow approval step"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/flows:
    get:
      summary: "List workflows through legacy flow alias"
    post:
      summary: "Create workflow through legacy flow alias"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/health:
    get:
      summary: "Service health v1 alias"
  /api/v1/agent-policy:
    get:
      summary: "AgentUI public/protected agent policy"
  /api/v1/agent-policy/platforms:
    get:
      summary: "List agent platform policies"
  /api/v1/agent-policy/platforms/{id}:
    get:
      summary: "Get agent platform policy"
  /api/v1/agent-policy/robots:
    get:
      summary: "Robots policy JSON"
  /api/v1/agent-policy/summary:
    get:
      summary: "Agent policy summary"
  /api/v1/prompts:
    get:
      summary: "List AgentUI MCP prompts"
  /api/v1/publish:
    get:
      summary: "List public workflow publications"
    post:
      summary: "Create workflow publication"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/resources:
    get:
      summary: "List AgentUI MCP resources"
  /api/v1/runs:
    get:
      summary: "List public-safe workflow runs"
  /api/v1/runs/{id}:
    get:
      summary: "Get public-safe workflow run"
  /api/v1/runs/{id}/artifacts:
    get:
      summary: "List public-safe workflow run artifacts"
  /api/v1/runs/{id}/blocks/{blockId}:
    get:
      summary: "Get selected block input, output, artifacts, evidence, and trace packet for a run"
  /api/v1/runs/{id}/cancel:
    post:
      summary: "Cancel workflow run"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/runs/{id}/events:
    get:
      summary: "SSE stream with public-safe run/delegation event snapshot and degraded polling fallback guidance"
  /api/v1/runs/{id}/steps:
    get:
      summary: "List public-safe workflow run steps"
  /api/v1/runs/{id}/steps/{stepId}:
    get:
      summary: "Get one workflow run step with block input/output view payload"
  /api/v1/runs/{id}/trace:
    get:
      summary: "Get public-safe workflow run trace link"
  /api/v1/services:
    get:
      summary: "List registered network services"
    post:
      summary: "Register network service"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/stats/runs:
    get:
      summary: "Get public-safe run statistics"
  /api/v1/templates:
    get:
      summary: "List workflow templates"
  /api/v1/templates/{id}:
    get:
      summary: "Get workflow template"
  /api/v1/templates/{id}/instantiate:
    post:
      summary: "Instantiate workflow template"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/render/mcp-tool:
    post:
      summary: "Render MCP tool schema into AgentUI form fields"
      operationId: "renderMcpToolForm"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                toolName:
                  type: "string"
                  default: "get_health"
                tool:
                  type: "object"
                  description: "Inline MCP tool definition when not using a registry tool."
                arguments:
                  type: "object"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/render/openapi-operation:
    post:
      summary: "Render OpenAPI operation into AgentUI form fields"
      operationId: "renderOpenApiOperationForm"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                operationId:
                  type: "string"
                  default: "getHealth"
                method:
                  type: "string"
                  enum:
                    - "get"
                    - "post"
                    - "put"
                    - "delete"
                path:
                  type: "string"
                  default: "/api/health"
                serviceBaseUrl:
                  type: "string"
                  format: "uri"
                  default: "https://agentui.platphormnews.com"
                operation:
                  type: "object"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/render/json-schema:
    post:
      summary: "Render JSON Schema into AgentUI form fields"
      operationId: "renderJsonSchemaForm"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                schema:
                  type: "object"
                sourceRef:
                  type: "string"
                title:
                  type: "string"
              required:
                - "schema"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/render/webhook-schema:
    post:
      summary: "Render webhook payload schema into AgentUI form fields"
      operationId: "renderWebhookSchemaForm"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                eventName:
                  type: "string"
                schema:
                  type: "object"
                serviceBaseUrl:
                  type: "string"
                  format: "uri"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/render/artifact:
    post:
      summary: "Render an AgentUI artifact model as form fields"
      operationId: "renderAgentUiArtifactForm"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                artifact:
                  type: "object"
                schema:
                  type: "object"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/render/workflow-node:
    post:
      summary: "Render workflow node configuration form"
      operationId: "renderWorkflowNodeForm"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                nodeType:
                  type: "string"
                  default: "mcp_tool"
                toolName:
                  type: "string"
                operationId:
                  type: "string"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/validate/form-input:
    post:
      summary: "Validate rendered form input without executing a tool"
      operationId: "validateFormInput"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                schema:
                  type: "object"
                value:
                  type: "object"
              required:
                - "schema"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/rendered-forms/{id}:
    get:
      summary: "Get rendered form persistence status"
  /api/v1/artifacts:
    get:
      summary: "List server-persisted AgentUI artifacts or honest degraded storage status"
    post:
      summary: "Create generated AgentUI artifact snapshot or protected persistence request"
  /api/v1/artifacts/{id}:
    get:
      summary: "Get AgentUI artifact storage status by id"
    put:
      summary: "Update server-persisted artifact"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
    delete:
      summary: "Delete server-persisted artifact"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/artifacts/{id}/view:
    get:
      summary: "Get artifact view-pane status and fallback panels"
  /api/v1/artifacts/{id}/clone:
    post:
      summary: "Clone an AgentUI artifact as a generated snapshot"
  /api/v1/artifacts/{id}/share:
    post:
      summary: "Create AgentUI share packet for an artifact"
  /api/v1/artifacts/{id}/export:
    post:
      summary: "Export AgentUI artifact as JSON, YAML, or Markdown"
  /api/v1/artifacts/{id}/delegate/{service}:
    post:
      summary: "Create a delegation packet for an artifact and target service"
  /api/v1/delegations:
    get:
      summary: "List delegation target registry, supported statuses, and confirmation policy"
  /api/v1/delegations/{id}:
    get:
      summary: "Get degraded durable delegation lookup status without claiming target confirmation"
  /api/v1/delegations/{id}/retry:
    post:
      summary: "Retry protected delegation"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/delegate/{service}:
    post:
      summary: "Create preview_ready, protected_required, not_configured, or degraded delegation envelope for a target PlatPhorm service"
  /api/v1/storage/status:
    get:
      summary: "Get AgentUI storage truth model and optionally run a public-safe database accessibility probe"
      parameters:
        - name: "probe"
          in: "query"
          required: false
          schema:
            type: "boolean"
        - name: "maxTables"
          in: "query"
          required: false
          schema:
            type: "integer"
            minimum: 0
            maximum: 50
  /api/v1/storage/modes:
    get:
      summary: "List AgentUI storage modes"
  /api/v1/storage/export:
    post:
      summary: "Export an AgentUI artifact packet"
  /api/v1/storage/import:
    post:
      summary: "Import an AgentUI artifact as a generated snapshot"
  /api/v1/integrations:
    get:
      summary: "List AgentUI integration matrix"
  /api/v1/integrations/status:
    get:
      summary: "Summarize integration status"
  /api/v1/integrations/{slug}:
    get:
      summary: "Get integration by slug"
  /api/v1/integrations/phorm/status:
    get:
      summary: "Get Phorm integration status"
  /api/v1/integrations/cli/status:
    get:
      summary: "Get CLI integration status"
  /api/v1/phorm/templates:
    get:
      summary: "List deterministic Phorm fallback templates"
  /api/v1/phorm/design-preview:
    post:
      summary: "Preview Phorm prompt-to-interface design or degraded fallback"
      operationId: "previewPhormDesign"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                prompt:
                  type: "string"
                  description: "Public-safe prompt. Do not include secrets."
                templateId:
                  type: "string"
                  default: "tool-form-panel"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/phorm/import-design:
    post:
      summary: "Import confirmed Phorm design"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/phorm/convert-to-workflow:
    post:
      summary: "Convert Phorm design reference to local workflow draft plan"
      operationId: "convertPhormDesignToWorkflow"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                designId:
                  type: "string"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/phorm/exports/{id}:
    get:
      summary: "Get Phorm export status"
  /api/v1/cli/examples:
    get:
      summary: "List platphormctl examples"
  /api/v1/cli/examples/{id}:
    get:
      summary: "Get platphormctl example"
  /api/v1/cli/validate-command:
    post:
      summary: "Validate platphormctl command shape without claiming execution"
      operationId: "validateCliCommand"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                command:
                  type: "string"
                  default: "platphormctl site inspect agentui --best-effort"
              required:
                - "command"
      responses:
        200:
          description: "JSON response with { ok, data } or JSON-RPC response where documented."
  /api/v1/tools:
    get:
      summary: "List AgentUI MCP tools"
  /api/v1/traces:
    get:
      summary: "List public-safe workflow traces"
  /api/v1/traces/{id}:
    get:
      summary: "Get public-safe workflow trace"
    delete:
      summary: "Delete workflow trace"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/ui/summary:
    get:
      summary: "Get public-safe AgentUI dashboard summary"
  /api/web4/status:
    get:
      summary: "Get AgentUI Web4 readiness, route evidence, privacy, storage, and integration status"
  /api/web4/manifest:
    get:
      summary: "Get AgentUI Web4 manifest as REST JSON envelope"
  /api/web4/scorecard:
    get:
      summary: "Get AgentUI Web4 scorecard with route, renderer, policy, trace, and provenance checks"
  /api/web4/fingerprints:
    get:
      summary: "List public-safe AgentUI fingerprints with privacy class and anchor eligibility"
  /api/web4/route-evidence:
    get:
      summary: "Return declared route evidence or actively fetch the fixed AgentUI route list when fetch=true"
      parameters:
        - name: "fetch"
          in: "query"
          required: false
          schema:
            type: "boolean"
        - name: "limit"
          in: "query"
          required: false
          schema:
            type: "integer"
            minimum: 1
        - name: "timeoutMs"
          in: "query"
          required: false
          schema:
            type: "integer"
            minimum: 250
            maximum: 10000
  /api/provenance/lookup:
    get:
      summary: "Lookup public-safe AgentUI provenance by url, hash, workflowId, runId, artifactId, delegationId, or formId"
      parameters:
        - name: "url"
          in: "query"
          required: false
          schema:
            type: "string"
        - name: "hash"
          in: "query"
          required: false
          schema:
            type: "string"
        - name: "recordId"
          in: "query"
          required: false
          schema:
            type: "string"
  /api/provenance/verify:
    get:
      summary: "Verify a public-safe AgentUI provenance record by recordId or hash"
      parameters:
        - name: "recordId"
          in: "query"
          required: false
          schema:
            type: "string"
        - name: "hash"
          in: "query"
          required: false
          schema:
            type: "string"
  /api/v1/workflows:
    get:
      summary: "List public-safe workflows"
    post:
      summary: "Create workflow"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/workflows/{id}:
    get:
      summary: "Get public-safe workflow by id"
    put:
      summary: "Update workflow"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
    delete:
      summary: "Delete workflow"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/workflows/{id}/dry-run:
    post:
      summary: "Dry-run workflow"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/workflows/{id}/blocks/{blockId}/dry-run:
    post:
      summary: "Dry-run one workflow block and return viewable input/output packet"
  /api/v1/workflows/{id}/blocks/{blockId}/run:
    post:
      summary: "Run one workflow block and persist a run packet"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/workflows/{id}/plan:
    post:
      summary: "Plan workflow without executing protected tools"
  /api/v1/workflows/{id}/publish:
    post:
      summary: "Publish workflow"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/workflows/{id}/run:
    post:
      summary: "Run workflow"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/workflows/{id}/validate:
    post:
      summary: "Validate workflow graph"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
  /api/v1/workflows/{id}/versions:
    get:
      summary: "List workflow versions"
    post:
      summary: "Create workflow version"
      security:
        - PlatphormApiKeyBearer:
[]
        - PlatphormApiKeyHeader:
[]
