{
  "openapi": "3.1.0",
  "info": {
    "title": "Sprello Public API",
    "version": "1.0.0",
    "summary": "Public agent endpoints and the Sprello Workflow API surface.",
    "description": "Sprello (sprello.ai) is the AI creative engine for consumer brands: a visual workflow canvas for producing brand-quality images, video, and copy at catalog scale. The endpoints under /api/v1 marked with no security are public and JSON-only, intended for AI agents and integrations that need structured facts about Sprello. Workflow endpoints (listing workflows, triggering runs) require a Workflow API key granted per workspace — request access at https://sprello.ai/api-access. All errors are structured JSON (see the Error schema).",
    "contact": {
      "name": "Sprello",
      "email": "contact@sprello.ai",
      "url": "https://sprello.ai/contact"
    },
    "termsOfService": "https://sprello.ai/tos"
  },
  "externalDocs": {
    "description": "Sprello developer resources",
    "url": "https://sprello.ai/developers"
  },
  "servers": [{ "url": "https://sprello.ai/api/v1" }],
  "security": [],
  "paths": {
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Service status",
        "description": "Liveness check for the Sprello public API. Returns the service name, API version, and current server time. No authentication required.",
        "tags": ["public"],
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Status" }
              }
            }
          }
        }
      }
    },
    "/product": {
      "get": {
        "operationId": "getProduct",
        "summary": "Product overview",
        "description": "Structured overview of Sprello: name, description, capabilities, target audience, and links to documentation, the OpenAPI spec, the MCP server, and pricing. No authentication required.",
        "tags": ["public"],
        "responses": {
          "200": {
            "description": "Product information.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Product" }
              }
            }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "Pricing plans",
        "description": "Current Sprello self-serve pricing plans (Starter, Pro, Scale, Enterprise) with monthly and yearly USD prices, included monthly generation credits, and plan features. No authentication required.",
        "tags": ["public"],
        "responses": {
          "200": {
            "description": "Pricing plans.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Pricing" }
              }
            }
          }
        }
      }
    },
    "/workflows": {
      "get": {
        "operationId": "listWorkflows",
        "summary": "List workflows",
        "description": "List the workflows in your Sprello workspace, paginated with an opaque cursor. Requires a Workflow API key; request access at https://sprello.ai/api-access. Without a valid key this returns a structured 401 error.",
        "tags": ["workflows"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of workflows to return per page (1-100, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque pagination cursor from a previous response's nextCursor field.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Workflows in the workspace.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WorkflowList" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/workflows/{workflowId}/runs": {
      "post": {
        "operationId": "createWorkflowRun",
        "summary": "Trigger a workflow run",
        "description": "Trigger a run of a published Sprello workflow with JSON inputs (text, image URLs, parameters). The response includes run status and output asset URLs. Requires a Workflow API key; request access at https://sprello.ai/api-access.",
        "tags": ["workflows"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "workflowId",
            "in": "path",
            "required": true,
            "description": "Identifier of the workflow to run.",
            "schema": { "type": "string" }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique client-generated key (e.g. a UUID). Retrying a request with the same key returns the original run instead of creating a duplicate.",
            "schema": { "type": "string", "maxLength": 255 }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WorkflowRunRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Run created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WorkflowRun" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Workflow not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/workflows/{workflowId}/runs/{runId}": {
      "get": {
        "operationId": "getWorkflowRun",
        "summary": "Get workflow run status",
        "description": "Poll the status of an asynchronous workflow run. Runs move through queued, running, and then succeeded or failed; on success the response includes output asset URLs. Requires a Workflow API key.",
        "tags": ["workflows"],
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "workflowId",
            "in": "path",
            "required": true,
            "description": "Identifier of the workflow.",
            "schema": { "type": "string" }
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "description": "Identifier of the run, from the createWorkflowRun response.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Current run state.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WorkflowRun" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Run not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Sprello Workflow API key, granted per workspace. Request access at https://sprello.ai/api-access."
      }
    },
    "schemas": {
      "Status": {
        "type": "object",
        "required": ["status", "service", "version", "time"],
        "properties": {
          "status": { "type": "string", "enum": ["ok"] },
          "service": { "type": "string" },
          "version": { "type": "string" },
          "time": { "type": "string", "format": "date-time" }
        }
      },
      "Product": {
        "type": "object",
        "required": ["name", "url", "description", "capabilities", "links"],
        "properties": {
          "name": { "type": "string" },
          "legalName": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "category": { "type": "string" },
          "audience": { "type": "array", "items": { "type": "string" } },
          "capabilities": { "type": "array", "items": { "type": "string" } },
          "links": {
            "type": "object",
            "additionalProperties": { "type": "string", "format": "uri" }
          }
        }
      },
      "Pricing": {
        "type": "object",
        "required": ["currency", "plans"],
        "properties": {
          "currency": { "type": "string" },
          "billingIntervals": {
            "type": "array",
            "items": { "type": "string" }
          },
          "note": { "type": "string" },
          "checkout": { "type": "string", "format": "uri" },
          "plans": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PricingPlan" }
          }
        }
      },
      "PricingPlan": {
        "type": "object",
        "required": ["name", "description", "features"],
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "monthlyUsd": { "type": ["number", "null"] },
          "yearlyUsd": { "type": ["number", "null"] },
          "monthlyCredits": { "type": ["integer", "null"] },
          "features": { "type": "array", "items": { "type": "string" } }
        }
      },
      "WorkflowList": {
        "type": "object",
        "required": ["workflows"],
        "properties": {
          "workflows": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Workflow" }
          },
          "nextCursor": {
            "type": ["string", "null"],
            "description": "Cursor for the next page, or null when this is the last page."
          }
        }
      },
      "Workflow": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" }
        }
      },
      "WorkflowRunRequest": {
        "type": "object",
        "description": "Inputs for the workflow run. Keys map to the workflow's input nodes.",
        "properties": {
          "inputs": {
            "type": "object",
            "description": "Input values keyed by input-node name: strings for text inputs, URLs for image/video inputs.",
            "additionalProperties": true
          }
        }
      },
      "WorkflowRun": {
        "type": "object",
        "required": ["id", "status"],
        "properties": {
          "id": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "succeeded", "failed"]
          },
          "outputs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": { "type": "string" },
                "url": { "type": "string", "format": "uri" }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code, e.g. unauthorized, invalid_api_key, not_found."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "hint": {
                "type": "string",
                "description": "How to resolve the error."
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "Link to relevant documentation."
              }
            }
          }
        }
      }
    }
  }
}