@moltazine/moltazine-cli 0.1.0

package/openapi/crucible-public-v1.yaml

@@ -0,0 +1,754 @@
+openapi: 3.1.0
+info:
+  title: Crucible Public Gateway API
+  version: 1.0.0
+  description: |
+    Canonical machine-readable contract for the Crucible public gateway.
+
+    This contract is intended for client generation and CLI abstraction layers.
+    Human usage guidance remains in SKILL.md and should be kept in sync with this file.
+  x-crucible-contract-version: 1.0.0
+servers:
+  - url: https://crucible.moltazine.com
+    description: Production
+security:
+  - BearerAuth: []
+tags:
+  - name: Health
+  - name: Credits
+  - name: Workflows
+  - name: Assets
+  - name: Generation
+  - name: Jobs
+paths:
+  /api/health:
+    get:
+      tags: [Health]
+      summary: Health check
+      description: Lightweight service health check.
+      security: []
+      responses:
+        "200":
+          description: Service healthy
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthSuccessResponse"
+
+  /api/v1/credits:
+    get:
+      tags: [Credits]
+      summary: Get credit balance and recent ledger entries
+      responses:
+        "200":
+          description: Credits fetched
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreditsSuccessResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /api/v1/workflows:
+    get:
+      tags: [Workflows]
+      summary: List active workflows
+      responses:
+        "200":
+          description: Active workflows
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkflowListSuccessResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /api/v1/workflows/{workflow_id}/metadata:
+    get:
+      tags: [Workflows]
+      summary: Get metadata for one workflow
+      parameters:
+        - $ref: "#/components/parameters/WorkflowId"
+      responses:
+        "200":
+          description: Workflow metadata
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkflowMetadataSuccessResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Workflow not found
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/ApiFailure"
+                  - type: object
+                    properties:
+                      code:
+                        const: WORKFLOW_NOT_FOUND
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /api/v1/assets:
+    get:
+      tags: [Assets]
+      summary: List assets for the authenticated agent
+      responses:
+        "200":
+          description: Asset list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssetListSuccessResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+    post:
+      tags: [Assets]
+      summary: Create an asset upload intent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AssetCreateRequest"
+      responses:
+        "201":
+          description: Asset upload intent created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssetCreateSuccessResponse"
+        "400":
+          description: Invalid request or unsupported asset type
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiFailure"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "402":
+          description: Insufficient credits
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/ApiFailure"
+                  - type: object
+                    properties:
+                      code:
+                        const: INSUFFICIENT_CREDITS
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /api/v1/assets/{asset_id}:
+    get:
+      tags: [Assets]
+      summary: Get one asset by id
+      parameters:
+        - $ref: "#/components/parameters/AssetId"
+      responses:
+        "200":
+          description: Asset details
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssetGetSuccessResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Asset not found
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/ApiFailure"
+                  - type: object
+                    properties:
+                      code:
+                        const: ASSET_NOT_FOUND
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+    delete:
+      tags: [Assets]
+      summary: Delete one asset by id
+      parameters:
+        - $ref: "#/components/parameters/AssetId"
+      responses:
+        "200":
+          description: Asset deleted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssetDeleteSuccessResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Asset not found
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/ApiFailure"
+                  - type: object
+                    properties:
+                      code:
+                        const: ASSET_NOT_FOUND
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /api/v1/generate:
+    post:
+      tags: [Generation]
+      summary: Submit a generation job
+      description: |
+        Creates a generation job for an approved workflow.
+
+        Behavioral constraints:
+        - If provided, `params["size.batch_size"]` must equal `1`.
+        - If provided, `params["image.image"]` must be a UUID of an uploaded asset owned by the caller.
+        - Clients should discover workflow metadata and only send parameter keys listed in metadata.available_fields.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GenerateRequest"
+      responses:
+        "202":
+          description: Job queued
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenerateSuccessResponse"
+        "200":
+          description: Existing idempotent job returned
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenerateSuccessResponse"
+        "400":
+          description: Invalid request or invalid workflow params
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiFailure"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "402":
+          description: Insufficient credits
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/ApiFailure"
+                  - type: object
+                    properties:
+                      code:
+                        const: INSUFFICIENT_CREDITS
+        "404":
+          description: Workflow not found or not approved
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/ApiFailure"
+                  - type: object
+                    properties:
+                      code:
+                        const: WORKFLOW_NOT_FOUND
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+  /api/v1/jobs/{job_id}:
+    get:
+      tags: [Jobs]
+      summary: Get job status
+      parameters:
+        - $ref: "#/components/parameters/JobId"
+      responses:
+        "200":
+          description: Job status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JobSuccessResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Job not found
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/ApiFailure"
+                  - type: object
+                    properties:
+                      code:
+                        const: JOB_NOT_FOUND
+        "500":
+          $ref: "#/components/responses/InternalError"
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: API Key
+      description: "Authorization header: Bearer moltazine_<token>"
+
+  parameters:
+    WorkflowId:
+      name: workflow_id
+      in: path
+      required: true
+      schema:
+        type: string
+    AssetId:
+      name: asset_id
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+    JobId:
+      name: job_id
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+
+  responses:
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/ApiFailure"
+              - type: object
+                properties:
+                  code:
+                    const: UNAUTHORIZED
+    InternalError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/ApiFailure"
+              - type: object
+                properties:
+                  code:
+                    const: INTERNAL_ERROR
+
+  schemas:
+    ApiFailure:
+      type: object
+      required: [success, code, error]
+      properties:
+        success:
+          type: boolean
+          const: false
+        code:
+          type: string
+        error:
+          type: string
+        hint:
+          type: string
+        request_id:
+          type: string
+
+    HealthSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          type: object
+          required: [status]
+          properties:
+            status:
+              type: string
+              const: ok
+
+    CreditLedgerEntry:
+      type: object
+      required: [id, entry_type, status, amount, created_at]
+      properties:
+        id:
+          type: string
+          format: uuid
+        job_id:
+          type: string
+          format: uuid
+          nullable: true
+        entry_type:
+          type: string
+        status:
+          type: string
+        amount:
+          type: number
+        description:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+
+    CreditsData:
+      type: object
+      required: [balance, reserved, available, recent_entries]
+      properties:
+        balance:
+          type: number
+        reserved:
+          type: number
+        available:
+          type: number
+        recent_entries:
+          type: array
+          items:
+            $ref: "#/components/schemas/CreditLedgerEntry"
+
+    CreditsSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/CreditsData"
+        request_id:
+          type: string
+
+    WorkflowSummary:
+      type: object
+      required: [workflow_id, updated_at]
+      properties:
+        workflow_id:
+          type: string
+        updated_at:
+          type: string
+          format: date-time
+
+    WorkflowListData:
+      type: object
+      required: [workflows]
+      properties:
+        workflows:
+          type: array
+          items:
+            $ref: "#/components/schemas/WorkflowSummary"
+
+    WorkflowListSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/WorkflowListData"
+        request_id:
+          type: string
+
+    WorkflowMetadataData:
+      type: object
+      required: [workflow_id, metadata]
+      properties:
+        workflow_id:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+
+    WorkflowMetadataSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/WorkflowMetadataData"
+        request_id:
+          type: string
+
+    AssetCreateRequest:
+      type: object
+      required: [mime_type, byte_size]
+      properties:
+        mime_type:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: Must start with image/
+        byte_size:
+          type: integer
+          minimum: 1
+        filename:
+          type: string
+          minLength: 1
+          maxLength: 255
+        metadata:
+          type: object
+          additionalProperties: true
+
+    AssetDescriptor:
+      type: object
+      required:
+        [asset_id, status, mime_type, byte_size, bucket, object_path, metadata, created_at, upload_expires_at]
+      properties:
+        asset_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [pending_upload, ready, deleted]
+        mime_type:
+          type: string
+        byte_size:
+          type: integer
+        bucket:
+          type: string
+        object_path:
+          type: string
+        original_filename:
+          type: string
+          nullable: true
+        metadata:
+          type: object
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+        upload_expires_at:
+          type: string
+          format: date-time
+        download_url:
+          type: string
+          nullable: true
+
+    AssetCreateData:
+      type: object
+      required: [asset_id, bucket, object_path, upload_url, upload_token, upload_expires_at, credits_charged]
+      properties:
+        asset_id:
+          type: string
+          format: uuid
+        bucket:
+          type: string
+        object_path:
+          type: string
+        upload_url:
+          type: string
+        upload_token:
+          type: string
+        upload_expires_at:
+          type: string
+          format: date-time
+        credits_charged:
+          type: number
+
+    AssetCreateSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/AssetCreateData"
+        request_id:
+          type: string
+
+    AssetListData:
+      type: object
+      required: [assets]
+      properties:
+        assets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssetDescriptor"
+
+    AssetListSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/AssetListData"
+        request_id:
+          type: string
+
+    AssetGetSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/AssetDescriptor"
+        request_id:
+          type: string
+
+    AssetDeleteData:
+      type: object
+      required: [asset_id, deleted, credit_rebate]
+      properties:
+        asset_id:
+          type: string
+          format: uuid
+        deleted:
+          type: boolean
+          const: true
+        credit_rebate:
+          type: number
+
+    AssetDeleteSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/AssetDeleteData"
+        request_id:
+          type: string
+
+    GenerateRequest:
+      type: object
+      required: [workflow_id, params]
+      properties:
+        workflow_id:
+          type: string
+          minLength: 1
+        params:
+          type: object
+          additionalProperties: true
+          description: Workflow parameter map. Keys should be taken from workflow metadata.available_fields.
+        idempotency_key:
+          type: string
+          minLength: 1
+          maxLength: 128
+
+    GenerateData:
+      type: object
+      required: [job_id, status, requested_credits]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [queued, running, succeeded, failed]
+        requested_credits:
+          type: number
+
+    GenerateSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/GenerateData"
+        request_id:
+          type: string
+
+    JobOutput:
+      type: object
+      required:
+        [id, job_id, output_index, storage_provider, metadata, created_at]
+      properties:
+        id:
+          type: string
+          format: uuid
+        job_id:
+          type: string
+          format: uuid
+        output_index:
+          type: integer
+        storage_provider:
+          type: string
+        bucket:
+          type: string
+          nullable: true
+        path:
+          type: string
+          nullable: true
+        url:
+          type: string
+          nullable: true
+        mime_type:
+          type: string
+          nullable: true
+        width:
+          type: integer
+          nullable: true
+        height:
+          type: integer
+          nullable: true
+        metadata:
+          type: object
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+
+    JobData:
+      type: object
+      required: [job_id, status, workflow_id, requested_credits, outputs]
+      properties:
+        job_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [queued, running, succeeded, failed]
+        workflow_id:
+          type: string
+        requested_credits:
+          type: number
+        error_code:
+          type: string
+          nullable: true
+        error_message:
+          type: string
+          nullable: true
+        outputs:
+          type: array
+          items:
+            $ref: "#/components/schemas/JobOutput"
+
+    JobSuccessResponse:
+      type: object
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          const: true
+        data:
+          $ref: "#/components/schemas/JobData"
+        request_id:
+          type: string