{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Naumio CropCheck", "version": "0.1.1", "description": "Authenticated, deterministic tools for non-sensitive integration evaluation. Prepare returns usable bytes. Digests bind content; they are not human consent. Muse rendering, downloads and user authorization remain subject to separate provider integration review." }, "servers": [ { "url": "https://muse-api.naumio.com", "description": "Authenticated endpoint; no anonymous tool processing." } ], "tags": [ { "name": "CropCheck", "description": "Deterministic static-image Fit/Cover PNGs and ZIP; no AI redraw." }, { "name": "Service Closeout", "description": "Supplied-evidence PDF; no truth certification or job completion inference." } ], "security": [ { "CallerBearer": [] } ], "paths": { "/api/crop/prepare": { "post": { "operationId": "prepareCrop", "tags": [ "CropCheck" ], "summary": "Prepare exact PNG previews", "description": "Validate original bytes/settings, normalize orientation and sRGB, flatten alpha onto chosen background. Show every output and warnings. Does not authenticate human review.", "x-core-request-body-max-bytes": 14000000, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropPrepareRequest" } } } }, "responses": { "200": { "description": "Existing core JSON result; generation is not download, sending, submission or approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropPrepareResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/Busy" }, "401": { "description": "Missing or invalid caller credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be exactly application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Origin unavailable or redirect rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Gateway configuration unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/crop/export": { "post": { "operationId": "exportCrop", "tags": [ "CropCheck" ], "summary": "Export content-bound crop ZIP", "description": "Resupply original image/settings and returned approvalDigest. Core recomputes PNGs and manifest before matching digest. ZIP contains PNGs and manifest.json. Never treat the digest alone as permission to send.", "x-core-request-body-max-bytes": 14000000, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropExportRequest" } } } }, "responses": { "200": { "description": "Existing core JSON result; generation is not download, sending, submission or approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CropExportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/Busy" }, "401": { "description": "Missing or invalid caller credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the endpoint byte limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be exactly application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Origin unavailable or redirect rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Gateway configuration unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "CallerBearer": { "type": "http", "scheme": "bearer", "description": "Dedicated integration credential in Authorization: Bearer. Obtain through an agreed secure exchange; never paste secrets into documentation. No OAuth or JWT format claimed." } }, "schemas": { "Digest": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Use the exact digest returned by prepare. Content binding only, not authentication, human consent, expiry or single-use proof." }, "Base64": { "type": "string", "minLength": 4, "contentEncoding": "base64", "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$", "description": "Canonical standard base64, not a URL or data URL. Content decoding/type validation remains a runtime check." }, "ImageBase64": { "allOf": [ { "$ref": "#/components/schemas/Base64" } ], "maxLength": 13333336, "description": "Static PNG/JPEG/WebP; decoded bytes 1..10000000 and decoded input pixels at most 24000000. Canonical base64 only; core decoder remains authoritative.", "x-decoded-max-bytes": 10000000, "x-max-input-pixels": 24000000 }, "PngDataUrl": { "type": "string", "pattern": "^data:image/png;base64,[A-Za-z0-9+/]+={0,2}$", "description": "Usable PNG bytes encoded as a data URL, not a remote artifact URL. Inspect all returned images." }, "TargetId": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,30}$" }, "CropTarget": { "type": "object", "additionalProperties": false, "required": [ "id", "width", "height", "mode" ], "properties": { "id": { "$ref": "#/components/schemas/TargetId" }, "width": { "type": "integer", "minimum": 16, "maximum": 4096 }, "height": { "type": "integer", "minimum": 16, "maximum": 4096 }, "mode": { "type": "string", "enum": [ "fit", "cover" ] }, "focalX": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }, "focalY": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 } } }, "CropRequest": { "type": "object", "additionalProperties": false, "required": [ "targets" ], "properties": { "targets": { "type": "array", "items": { "$ref": "#/components/schemas/CropTarget" }, "minItems": 1, "maxItems": 4, "description": "IDs must be unique. Sum(width*height) <= 24000000; intermediate raster <= 32000000 pixels and each dimension <= 32768. Cross-item constraints are checked by the core, not generic JSON Schema." }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#ffffff", "description": "Opaque background; transparency is flattened." } } }, "CropPrepareRequest": { "type": "object", "additionalProperties": false, "required": [ "imageBase64", "request" ], "properties": { "imageBase64": { "$ref": "#/components/schemas/ImageBase64" }, "request": { "$ref": "#/components/schemas/CropRequest" } } }, "CropExportRequest": { "type": "object", "additionalProperties": false, "required": [ "imageBase64", "request", "approvalDigest" ], "properties": { "imageBase64": { "$ref": "#/components/schemas/ImageBase64" }, "request": { "$ref": "#/components/schemas/CropRequest" }, "approvalDigest": { "$ref": "#/components/schemas/Digest" } } }, "Placement": { "type": "object", "additionalProperties": false, "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "integer" }, "y": { "type": "integer" }, "width": { "type": "integer", "minimum": 1, "maximum": 32768 }, "height": { "type": "integer", "minimum": 1, "maximum": 32768 } } }, "CropOutput": { "type": "object", "additionalProperties": false, "required": [ "id", "width", "height", "mode", "focalX", "focalY", "name", "sha256", "upscaled", "cropLoss", "placement", "warnings" ], "properties": { "id": { "$ref": "#/components/schemas/TargetId" }, "width": { "type": "integer", "minimum": 16, "maximum": 4096 }, "height": { "type": "integer", "minimum": 16, "maximum": 4096 }, "mode": { "type": "string", "enum": [ "fit", "cover" ] }, "focalX": { "type": "number", "minimum": 0, "maximum": 1 }, "focalY": { "type": "number", "minimum": 0, "maximum": 1 }, "name": { "type": "string", "minLength": 1, "description": "-x.png" }, "sha256": { "$ref": "#/components/schemas/Digest" }, "upscaled": { "type": "boolean" }, "cropLoss": { "type": "number", "description": "Geometric crop loss, not semantic safety or importance detection." }, "placement": { "$ref": "#/components/schemas/Placement" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "CropManifest": { "type": "object", "additionalProperties": false, "required": [ "schema", "sourceSha256", "sourceWidth", "sourceHeight", "background", "geometrySha256", "outputs", "notes" ], "properties": { "schema": { "const": "naumio.cropcheck.v1", "type": "string" }, "sourceSha256": { "$ref": "#/components/schemas/Digest" }, "sourceWidth": { "type": "integer", "minimum": 1 }, "sourceHeight": { "type": "integer", "minimum": 1 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "geometrySha256": { "$ref": "#/components/schemas/Digest" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/CropOutput" }, "minItems": 1, "maxItems": 4 }, "notes": { "type": "array", "items": { "type": "string" } } } }, "CropPrepareResponse": { "type": "object", "additionalProperties": false, "required": [ "manifest", "approvalDigest", "files" ], "properties": { "manifest": { "$ref": "#/components/schemas/CropManifest" }, "approvalDigest": { "$ref": "#/components/schemas/Digest" }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "dataUrl" ], "properties": { "name": { "type": "string", "minLength": 1 }, "dataUrl": { "$ref": "#/components/schemas/PngDataUrl" } } }, "minItems": 1, "maxItems": 4 } } }, "CropExportResponse": { "type": "object", "additionalProperties": false, "required": [ "manifest", "zipBase64" ], "properties": { "manifest": { "$ref": "#/components/schemas/CropManifest" }, "zipBase64": { "allOf": [ { "$ref": "#/components/schemas/Base64" } ], "contentMediaType": "application/zip", "description": "ZIP contains exact PNGs plus manifest.json, no original image. No third-party delivery is performed." } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "requestId": { "type": "string" } }, "additionalProperties": false } ] } } } }, "responses": { "BadRequest": { "description": "Existing shim: malformed JSON, input/decoder/font/renderer/resource failure or missing/stale approval. All handled processing errors use 400; not separate typed codes. Correct input or reprepare and obtain fresh review. Some stream/timeout failures instead terminate transport.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Existing shim: Host/Origin/local-token or exact Content-Type check failed. Not evidence of public authentication. Proposed adapter must supply its own authenticated rejection policy before release.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Existing shim: unknown route or unsupported method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Busy": { "description": "Existing shim: one process-global operation is active. No queue, per-user quota or Retry-After guarantee. Retry after completion; reconcile any uncertain external delivery separately.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }