{ "components": { "schemas": { "Action": { "enum": [ "accept", "review", "reject" ], "type": "string" }, "Answer": { "description": "What a check answers: openmod's report plus `request_id`,\n`workflow_version` and `ref`. Every plan gets every field.", "properties": { "ref": { "description": "Your own id for the content, as sent, or null.", "type": [ "string", "null" ] }, "request_id": { "description": "The id of this request, also in `X-Request-Id` and in the journal.", "type": "string" }, "scores": { "additionalProperties": { "format": "float", "type": "number" }, "description": "The best score per category the workflow checks, in [0, 1].", "propertyNames": { "type": "string" }, "type": "object" }, "status": { "description": "Always `success`.", "example": "success", "type": "string" }, "summary": { "$ref": "#/components/schemas/Summary" }, "time_ms": { "description": "Time spent checking, in milliseconds.", "format": "int64", "minimum": 0, "type": "integer" }, "unchecked": { "description": "Categories of the workflow this server could not check; absent when\nevery one was checked.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "workflow": { "description": "The workflow the content was checked against.", "type": "string" }, "workflow_version": { "description": "The version of the workflow that decided.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "status", "workflow", "summary", "scores", "time_ms", "request_id", "workflow_version" ], "type": "object" }, "CompatAnswer": { "description": "What the two SightEngine-compatible routes answer: the same fields as a\ncheck, with SightEngine's `request`, and `workflow` as an object.", "properties": { "ref": { "description": "Your own id for the content, as sent, or null.", "type": [ "string", "null" ] }, "request": { "$ref": "#/components/schemas/CompatRequest" }, "request_id": { "description": "The id of this request, also in `request.id` and `X-Request-Id`.", "type": "string" }, "scores": { "additionalProperties": { "format": "float", "type": "number" }, "description": "The best score per category the workflow checks, in [0, 1]. The\ncategory ids are openmod's own, not SightEngine's model fields.", "propertyNames": { "type": "string" }, "type": "object" }, "status": { "description": "Always `success`.", "example": "success", "type": "string" }, "summary": { "$ref": "#/components/schemas/Summary" }, "time_ms": { "description": "Time spent checking, in milliseconds.", "format": "int64", "minimum": 0, "type": "integer" }, "unchecked": { "description": "Categories of the workflow this server could not check; absent when\nevery one was checked.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "workflow": { "$ref": "#/components/schemas/CompatWorkflow", "description": "The workflow the content was checked against." }, "workflow_version": { "description": "The version of the workflow that decided.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "status", "request", "workflow", "summary", "scores", "time_ms", "request_id", "workflow_version" ], "type": "object" }, "CompatErrorEnvelope": { "description": "openmod's error envelope, with `request` as the compat routes send it.", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" }, "request": { "$ref": "#/components/schemas/CompatRequest" }, "status": { "description": "Always `failure`.", "example": "failure", "type": "string" } }, "required": [ "status", "request", "error" ], "type": "object" }, "CompatImageForm": { "description": "The SightEngine-compatible image form. The key is inside it, so the whole\nform must arrive within 10 s, and every field but `media` holds at most\n64 KiB.", "properties": { "api_secret": { "description": "The API key.", "type": [ "string", "null" ] }, "api_user": { "description": "Accepted and ignored.", "type": [ "string", "null" ] }, "media": { "description": "The image bytes; or send `url`.", "format": "binary", "type": [ "string", "null" ] }, "url": { "description": "The image's `http` or `https` address, downloaded by the server from\nthe public internet only: at most 15 MB, 3 redirects and 10 s, with\n`Content-Type: image/*`.", "type": [ "string", "null" ] }, "workflow": { "type": [ "string", "null" ] } }, "type": "object" }, "CompatRequest": { "description": "The `request` object of a compat answer or error.", "properties": { "id": { "description": "The id of this request, as in `X-Request-Id`.", "type": "string" }, "operations": { "description": "1 for a check that ran, 0 for a refusal.", "format": "int32", "minimum": 0, "type": "integer" }, "timestamp": { "description": "The gateway's clock when it answered, in seconds since the epoch.", "format": "double", "type": "number" } }, "required": [ "id", "timestamp", "operations" ], "type": "object" }, "CompatTextForm": { "description": "The SightEngine-compatible text form. The key is inside it, so the whole\nform must arrive within 10 s, and every field but `text` holds at most\n64 KiB.", "properties": { "api_secret": { "description": "The API key.", "type": [ "string", "null" ] }, "api_user": { "description": "Accepted and ignored.", "type": [ "string", "null" ] }, "text": { "description": "At most 20,000 characters, and 5,000 on the free plan.", "type": "string" }, "workflow": { "type": [ "string", "null" ] } }, "required": [ "text" ], "type": "object" }, "CompatWorkflow": { "description": "The workflow of a compat answer.", "properties": { "id": { "description": "The workflow's name.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "ErrorBody": { "properties": { "code": { "description": "The HTTP status, repeated.", "format": "int32", "minimum": 0, "type": "integer" }, "message": { "description": "What went wrong, in English.", "type": "string" }, "type": { "description": "A stable type to switch on: `unauthorized`, `forbidden`,\n`organization_suspended`, `bad_request`,\n`unknown_workflow`, `unsupported_media`, `corrupt_media`,\n`body_too_large`, `image_too_large`, `text_too_long`,\n`workflow_unavailable`, `request_timeout`, `rate_limited`,\n`too_many_concurrent`, `quota_exceeded`, `url_refused`, `busy`,\n`internal`.", "type": "string" } }, "required": [ "type", "code", "message" ], "type": "object" }, "ErrorEnvelope": { "description": "openmod's error envelope.", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" }, "status": { "description": "Always `failure`.", "example": "failure", "type": "string" } }, "required": [ "status", "error" ], "type": "object" }, "Health": { "properties": { "status": { "description": "`ok`, or `unavailable` with status 503.", "type": "string" } }, "required": [ "status" ], "type": "object" }, "Reason": { "description": "One category that reached its threshold.", "properties": { "id": { "description": "The category id (`nudity`, `pii_iban`): map it to your own messages.", "type": "string" }, "message": { "description": "A full English sentence that can be shown to an end user.", "type": "string" }, "score": { "format": "float", "type": "number" }, "source": { "description": "The tool that produced the score.", "type": "string" }, "text": { "description": "A short English title.", "type": "string" }, "threshold": { "format": "float", "type": "number" } }, "required": [ "id", "text", "message", "score", "threshold", "source" ], "type": "object" }, "Summary": { "properties": { "action": { "$ref": "#/components/schemas/Action", "description": "`reject` when a reject threshold is reached, else `review` when a\nreview threshold is, else `accept`." }, "reject_prob": { "description": "The highest score among the rejected categories, 0 when none is.", "format": "float", "type": "number" }, "reject_reason": { "description": "Why the content is rejected, highest score first.", "items": { "$ref": "#/components/schemas/Reason" }, "type": "array" }, "review_reason": { "description": "Why the content goes to review, highest score first.", "items": { "$ref": "#/components/schemas/Reason" }, "type": "array" } }, "required": [ "action", "reject_prob", "reject_reason", "review_reason" ], "type": "object" }, "TextRequest": { "description": "The body of `POST /v1/text`.", "properties": { "context": { "description": "Where the text comes from, in plain words, e.g. \"a buyer writes to a\nseller on a second-hand marketplace\": at most 2,000 characters. Paid\nplans use it in their advanced AI workflows; the free plan ignores it.", "type": [ "string", "null" ] }, "ref": { "description": "Your own id for the text: 1 to 128 characters, no control character.", "type": [ "string", "null" ] }, "text": { "description": "At most 20,000 characters, and 5,000 on the free plan.", "type": "string" }, "workflow": { "description": "The workflow to check against; `default` when absent.", "type": [ "string", "null" ] } }, "required": [ "text" ], "type": "object" }, "WorkflowList": { "properties": { "status": { "description": "Always `success`.", "type": "string" }, "workflows": { "items": { "$ref": "#/components/schemas/WorkflowVersion" }, "type": "array" } }, "required": [ "status", "workflows" ], "type": "object" }, "WorkflowVersion": { "properties": { "name": { "type": "string" }, "version": { "description": "The current version, as `workflow_version` in answers.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "name", "version" ], "type": "object" } }, "securitySchemes": { "api_key": { "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "bearer": { "bearerFormat": "om_live__", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "email": "contact@sway.events", "name": "Sway SRL" }, "description": "Image and text moderation by openmod, the moderation API of openshield, hosted by Sway SRL. Call it from your servers only: a request with an Origin header is refused.", "license": { "identifier": "LicenseRef-Proprietary", "name": "LicenseRef-Proprietary" }, "title": "openshield API", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/1.0/check-workflow.json": { "get": { "operationId": "compat_image_get", "parameters": [ { "description": "The image's `http` or `https` address, downloaded by the server from the public internet only: at most 15 MB, 3 redirects and 10 s, with `Content-Type: image/*`. Required: a query cannot carry an image, so `media` there is a missing image.", "in": "query", "name": "url", "required": false, "schema": { "type": "string" } }, { "description": "The workflow to check against; `default` when absent.", "in": "query", "name": "workflow", "required": false, "schema": { "type": "string" } }, { "description": "Accepted and ignored.", "in": "query", "name": "api_user", "required": false, "schema": { "type": "string" } }, { "description": "The API key.", "in": "query", "name": "api_secret", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatAnswer" } } }, "description": "The decision, in SightEngine's shape" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A bad request, no `url`, an unknown workflow, a corrupt image or a refused `url` (`url_refused`, with the reason)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A missing, malformed, invalid, revoked or expired key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The key may not check images or use this workflow, the organization is suspended, or the request came from a browser" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "An image over the limits" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "Not an image" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "Rate limited, too many checks at once, or the quota reached; see Retry-After" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The workflow cannot run on this server, or the server is busy; retry after Retry-After" } }, "security": [ { "bearer": [] }, { "api_key": [] } ], "summary": "Checks an image by its address, SightEngine-compatible: `url`, `workflow`\nand the key in `api_secret` travel in the query string.", "tags": [ "checks" ] }, "post": { "operationId": "compat_image", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CompatImageForm" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatAnswer" } } }, "description": "The decision" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A bad request, an unknown workflow, a corrupt image or a refused `url` (`url_refused`, with the reason)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A missing, malformed, invalid, revoked or expired key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The key may not check images or use this workflow, or the organization is suspended" }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The form was not received within 10 s (`request_timeout`)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A body or an image over the limits, or a form field other than `media` over 64 KiB" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "Not an image" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "Rate limited, too many checks at once, or the quota reached; see Retry-After" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The workflow cannot run on this server, or the server is busy (too many uploads in progress); retry after Retry-After" } }, "security": [ { "bearer": [] }, { "api_key": [] } ], "summary": "Checks an image, SightEngine-compatible: the key travels in `api_secret`.", "tags": [ "checks" ] } }, "/1.0/text/check-workflow.json": { "post": { "operationId": "compat_text", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CompatTextForm" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatAnswer" } } }, "description": "The decision" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A bad request or an unknown workflow" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A missing, malformed, invalid, revoked or expired key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The key may not check texts or use this workflow, or the organization is suspended" }, "408": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The form was not received within 10 s (`request_timeout`)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "A body or a text over the limits, or a form field other than `text` over 64 KiB" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "Rate limited, too many checks at once, or the quota reached; see Retry-After" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatErrorEnvelope" } } }, "description": "The workflow cannot run on this server, or the server is busy (too many uploads in progress); retry after Retry-After" } }, "security": [ { "bearer": [] }, { "api_key": [] } ], "summary": "Checks a text, SightEngine-compatible: the key travels in `api_secret`.", "tags": [ "checks" ] } }, "/health": { "get": { "operationId": "health", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }, "description": "Ready" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }, "description": "Starting (no snapshot yet, or a model not loaded) or stopping" } }, "summary": "`{\"status\": \"ok\"}` once the engine and a snapshot are ready, `503`\nbefore and once a stop has begun: Caddy sends traffic only to a ready\nreplica. No details here.", "tags": [ "crate::api" ] } }, "/openapi.json": { "get": { "operationId": "openapi_json", "responses": { "200": { "content": { "application/json": {} }, "description": "The OpenAPI 3.1 document" } }, "summary": "The OpenAPI document of this API.", "tags": [ "crate::api" ] } }, "/v1/image": { "post": { "operationId": "check_image", "parameters": [ { "description": "The workflow to check against; `default` when absent.", "in": "query", "name": "workflow", "required": false, "schema": { "type": "string" } }, { "description": "Your own id for the image: 1 to 128 characters, no control character. Echoed and kept in the journal.", "in": "query", "name": "ref", "required": false, "schema": { "type": "string" } }, { "description": "The image's `http` or `https` address instead of a body, downloaded by the server from the public internet only: at most 15 MB, 3 redirects and 10 s, with `Content-Type: image/*`.", "in": "query", "name": "url", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": "array" } } }, "description": "The image: JPEG, PNG, WebP or GIF (first frame), at most 15 MB, 50 Mpixels (12 Mpixels on the free plan) and 16,384 px a side. Empty with `url=`.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Answer" } } }, "description": "The decision" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A bad request, an unknown workflow, a corrupt image, a refused `ref`, or a refused `url=` (`url_refused`, with the reason)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A missing, malformed, invalid, revoked or expired key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The key may not check this kind or use this workflow, the organization is suspended, or the request came from a browser" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A body, an image or a text over the limits" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not an image, or a text without the JSON content type" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited, too many checks at once, or the quota reached; see Retry-After" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The workflow cannot run on this server, or the server is busy; retry after Retry-After" } }, "security": [ { "bearer": [] }, { "api_key": [] } ], "summary": "Checks an image sent as the raw request body.", "tags": [ "checks" ] } }, "/v1/text": { "post": { "operationId": "check_text", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Answer" } } }, "description": "The decision" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A bad request, an unknown workflow or a refused `ref`" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A missing, malformed, invalid, revoked or expired key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The key may not check texts or use this workflow, the organization is suspended, or the request came from a browser" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A body or a text over the limits" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A text without the JSON content type" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited, too many checks at once, or the quota reached; see Retry-After" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The workflow cannot run on this server, or the server is busy; retry after Retry-After" } }, "security": [ { "bearer": [] }, { "api_key": [] } ], "summary": "Checks a text.", "tags": [ "checks" ] } }, "/v1/workflows": { "get": { "operationId": "list_workflows", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowList" } } }, "description": "The workflows" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A missing, malformed, invalid, revoked or expired key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The organization is suspended" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited; see Retry-After" } }, "security": [ { "bearer": [] }, { "api_key": [] } ], "summary": "The names and current versions of the workflows the key may use.", "tags": [ "crate::api" ] } } }, "servers": [ { "url": "https://api.openshield.dev" } ], "tags": [ { "description": "Check an image or a text against a workflow", "name": "checks" } ] }