{ "components": { "headers": { "Deprecation": { "description": "RFC 9745 deprecation date. Present only after a stable operation is formally deprecated.", "schema": { "example": "@1798761600", "type": "string" } }, "RateLimitLimit": { "description": "Maximum requests allowed in the current rate-limit window.", "schema": { "minimum": 0, "type": "integer" } }, "RateLimitPolicy": { "description": "Rate-limit policy and window emitted by express-rate-limit.", "schema": { "example": "1200;w=60", "type": "string" } }, "RateLimitRemaining": { "description": "Requests remaining in the current rate-limit window.", "schema": { "minimum": 0, "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the current rate-limit window resets.", "schema": { "minimum": 0, "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "minimum": 0, "type": "integer" } }, "Sunset": { "description": "RFC 8594 sunset date. Present only when removal has a published deadline.", "schema": { "example": "2028-01-01T00:00:00Z", "format": "date-time", "type": "string" } }, "XRequestId": { "description": "Stable request identifier for support correlation and distributed tracing.", "schema": { "example": "8d69dd0b-6a61-4432-a958-2f57612b61a4", "maxLength": 128, "minLength": 1, "type": "string" } } }, "parameters": { "ModelVersionChunkUploadId": { "description": "Upload-session identifier returned by the create operation.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "uploadId", "required": true, "schema": { "description": "Upload Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } } }, "responses": { "BadRequest": { "content": { "application/json": { "example": { "error": "The request is invalid.", "errorCode": "BAD_REQUEST", "retryable": false }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The request is malformed or fails operation-specific validation.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "Conflict": { "content": { "application/json": { "example": { "error": "The request conflicts with the current resource state.", "errorCode": "CONFLICT", "retryable": false }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The request conflicts with the current state of the target resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "Forbidden": { "content": { "application/json": { "example": { "error": "Access denied.", "errorCode": "FORBIDDEN", "retryable": false }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The authenticated principal does not have access to this operation.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "InternalServerError": { "content": { "application/json": { "example": { "error": "Something went wrong on the server.", "errorCode": "INTERNAL_ERROR", "retryable": false }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unexpected server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "ModelVersionChunkUploadBadRequest": { "content": { "application/json": { "example": { "error": "fileSize must be between 1 byte and 512 MiB" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "Request fields are invalid or the negotiated split would exceed the maximum chunk count.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "ModelVersionChunkUploadCancelled": { "content": { "application/json": { "example": { "error": "Upload session was cancelled" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "The upload session was cancelled and can no longer receive chunks or be completed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "ModelVersionChunkUploadForbidden": { "content": { "application/json": { "example": { "error": "Not allowed to access this upload session" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "The authenticated user cannot access this model or upload session.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "ModelVersionChunkUploadInterrupted": { "content": { "application/json": { "example": { "error": "Upload chunk transfer was interrupted. Please retry.", "errorCode": "UPLOAD_CHUNK_ABORTED", "retryable": true }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "The chunk request body was interrupted before it arrived in full. Query the session and retry the same chunk index if absent.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "ModelVersionChunkUploadNotFound": { "content": { "application/json": { "example": { "error": "Upload session not found", "errorCode": "UPLOAD_SESSION_NOT_FOUND", "retryable": false }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "The upload session does not exist or has been cleaned up after expiry. A chunk PUT is rejected before its body is read.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "ModelVersionChunkUploadQuotaExceeded": { "content": { "application/json": { "example": { "error": "Too many active model version upload sessions" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "Per-user quota exceeded. At most 3 active sessions and 1610612736 pending bytes are allowed. Cancel abandoned sessions before retrying.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "ModelVersionChunkUploadUnauthorized": { "content": { "application/json": { "example": { "error": "Invalid or expired token" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "Authentication is missing or invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "NotFound": { "content": { "application/json": { "example": { "error": "Requested resource not found.", "errorCode": "NOT_FOUND", "retryable": false }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The requested resource does not exist or is not visible to the current principal.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "TooManyRequests": { "content": { "application/json": { "example": { "error": "Too many requests, please retry later.", "errorCode": "RATE_LIMITED", "retryable": true }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The request exceeded an application or edge rate limit.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "Unauthorized": { "content": { "application/json": { "example": { "error": "Authentication required.", "errorCode": "UNAUTHORIZED", "retryable": false }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Authentication credentials are missing or invalid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "schemas": { "ApiError": { "additionalProperties": true, "description": "Standard Arc en Ciel error response.", "properties": { "details": { "additionalProperties": true, "description": "Optional structured error details.", "type": "object" }, "error": { "description": "Human-readable error message.", "example": "Request could not be completed.", "type": "string" }, "errorCode": { "description": "Stable machine-readable error code.", "example": "REQUEST_FAILED", "type": "string" }, "message": { "description": "Additional human-readable context.", "example": "Request could not be completed.", "type": "string" }, "retryable": { "description": "Whether the same request may succeed later. This is not permission for an SDK to retry an unsafe write; automatic retries still follow the operation x-sdk-retry-classification and Idempotency-Key contract.", "example": false, "type": "boolean" } }, "type": "object" }, "ApiKey": { "description": "Structured api keys item details for this api keys.", "example": { "createdAt": "2025-02-26T10:00:00Z", "expiresAt": null, "id": 42, "lastUsedAt": null, "name": "Automation key", "preview": "9fa3b7", "revokedAt": null, "scopeMask": 33554431, "usageCount": 0 }, "properties": { "createdAt": { "description": "UTC timestamp when this api keys item was created. Format: date-time.", "format": "date-time", "type": "string" }, "expiresAt": { "description": "UTC timestamp for the expires at transition of this api keys item. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "Stable identifier for the api keys item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "lastUsedAt": { "description": "UTC timestamp for the last used at transition of this api keys item. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this api keys item; it is not a stable identifier.", "nullable": true, "type": "string" }, "preview": { "description": "Preview associated with this api keys item; preserve server-returned values when passing them to another operation.", "type": "string" }, "revokedAt": { "description": "UTC timestamp for the revoked at transition of this api keys item. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "scopeMask": { "description": "Bitmask of API-key scopes. See components.x-api-key-scopes for the full scope table.", "type": "integer" }, "usageCount": { "description": "Number of usage records represented by this api keys item.", "type": "integer" } }, "type": "object" }, "Article": { "description": "Fields describing article in Developer API requests and responses.", "example": { "content": "

Example section

This is the content of the article.

", "createdAt": "2025-01-01T12:00:00Z", "id": 1, "tags": [ "ai", "stable diffusion" ], "thumbnailFile": "uploads/articles/example.png", "title": "Example Article", "updatedAt": "2025-01-01T12:00:00Z" }, "properties": { "bumpedAt": { "description": "UTC timestamp for the bumped at transition of this article. Format: date-time.", "format": "date-time", "type": "string" }, "content": { "description": "Sanitized rich HTML article body. Existing legacy Markdown remains render-compatible during migration.", "type": "string" }, "contentBumpedAt": { "description": "UTC timestamp for the content bumped at transition of this article. Format: date-time.", "format": "date-time", "type": "string" }, "createdAt": { "description": "UTC timestamp when this article was created. Format: date-time.", "format": "date-time", "type": "string" }, "id": { "description": "Stable identifier for the article; use it in subsequent API calls instead of a display name.", "type": "integer" }, "tags": { "description": "Ordered tags entries included with this article; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "thumbnailFile": { "description": "Thumbnail File associated with this article; preserve server-returned values when passing them to another operation.", "type": "string" }, "title": { "description": "Display title shown to users for this article.", "type": "string" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this article. Format: date-time.", "format": "date-time", "type": "string" } }, "type": "object" }, "CollabAvailabilityCounts": { "description": "Fields describing collab availability counts in Developer API requests and responses.", "properties": { "arc": { "description": "Numeric arc reported for this collab availability counts. Minimum: 0.", "minimum": 0, "type": "integer" }, "archive": { "description": "Numeric archive reported for this collab availability counts. Minimum: 0.", "minimum": 0, "type": "integer" }, "source": { "description": "Numeric source reported for this collab availability counts. Minimum: 0.", "minimum": 0, "type": "integer" }, "unavailable": { "description": "Numeric unavailable reported for this collab availability counts. Minimum: 0.", "minimum": 0, "type": "integer" } }, "required": [ "arc", "source", "archive", "unavailable" ], "type": "object" }, "CollabCollectionSummary": { "description": "Fields describing collab collection summary in Developer API requests and responses.", "properties": { "coverImage": { "description": "Cover Image associated with this collab collection summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "coverImageRating": { "description": "Cover Image Rating associated with this collab collection summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "id": { "description": "Stable identifier for the collab collection summary; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "modelCount": { "description": "Number of model records represented by this collab collection summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "name": { "description": "Human-readable name for this collab collection summary; it is not a stable identifier.", "type": "string" }, "slug": { "description": "Slug associated with this collab collection summary; preserve server-returned values when passing them to another operation.", "type": "string" }, "visibility": { "description": "Visibility associated with this collab collection summary; preserve server-returned values when passing them to another operation. Supported values: `PUBLIC`, `UNLISTED`, `PRIVATE`.", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE" ], "type": "string" } }, "required": [ "id", "slug", "name", "visibility", "modelCount" ], "type": "object" }, "CollabCoverImage": { "description": "Fields describing collab cover image in Developer API requests and responses.", "properties": { "external": { "description": "Whether external applies to this collab cover image.", "type": "boolean" }, "filePath": { "description": "Server-provided path for the file path associated with this collab cover image; treat it as opaque.", "type": "string" }, "height": { "description": "Numeric height reported for this collab cover image.", "nullable": true, "type": "integer" }, "id": { "description": "Stable identifier for the collab cover image; use it in subsequent API calls instead of a display name.", "type": "integer" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "rating": { "description": "Content-safety rating assigned to this collab cover image; callers must still apply their own audience policy.", "nullable": true, "type": "string" }, "sourceModelId": { "description": "Stable identifier for the source model; use it in subsequent API calls instead of a display name.", "type": "integer" }, "title": { "description": "Display title shown to users for this collab cover image.", "type": "string" }, "variants": { "additionalProperties": true, "description": "Structured variants details for this collab cover image.", "nullable": true, "type": "object" }, "width": { "description": "Numeric width reported for this collab cover image.", "nullable": true, "type": "integer" } }, "required": [ "id", "filePath", "external", "sourceModelId", "title" ], "type": "object" }, "CollabCreatorPreview": { "description": "Fields describing collab creator preview in Developer API requests and responses.", "properties": { "displayName": { "description": "Human-readable display name for this collab creator preview; it is not a stable identifier.", "type": "string" }, "localUser": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Local User associated with this collab creator preview; preserve server-returned values when passing them to another operation.", "nullable": true } }, "required": [ "displayName" ], "type": "object" }, "CollabDetail": { "allOf": [ { "$ref": "#/components/schemas/CollabSummary" }, { "description": "Fields describing collab detail in Developer API requests and responses.", "properties": { "currentParticipant": { "allOf": [ { "$ref": "#/components/schemas/CollabParticipant" } ], "description": "Current Participant associated with this collab detail; preserve server-returned values when passing them to another operation.", "nullable": true }, "evidence": { "description": "Ordered evidence entries included with this collab detail; an empty list means none are available.", "items": { "additionalProperties": true, "description": "Structured evidence item details for this evidence.", "type": "object" }, "type": "array" }, "historicalParticipants": { "description": "Ordered historical participants entries included with this collab detail; an empty list means none are available.", "items": { "additionalProperties": true, "description": "Structured historical participants item details for this historical participants.", "type": "object" }, "type": "array" }, "participants": { "description": "Ordered participants entries included with this collab detail; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollabParticipant" }, "type": "array" }, "permissions": { "$ref": "#/components/schemas/CollabPermissions" }, "updatedBy": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Updated By associated with this collab detail; preserve server-returned values when passing them to another operation.", "nullable": true } }, "required": [ "participants", "currentParticipant", "permissions" ], "type": "object" } ], "description": "Collab Detail value documented for this operation." }, "CollabPage": { "description": "Fields describing collab page in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this collab page; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollabSummary" }, "type": "array" }, "limit": { "description": "Maximum number of records requested or returned in one page of this collab page. Minimum: 1.", "minimum": 1, "type": "integer" }, "page": { "description": "One-based result page requested or returned for this collab page. Minimum: 1.", "minimum": 1, "type": "integer" }, "totalCount": { "description": "Total number of matching records across all pages for this collab page. Minimum: 0.", "minimum": 0, "type": "integer" }, "totalPages": { "description": "Total number of pages available at the current page size for this collab page. Minimum: 0.", "minimum": 0, "type": "integer" } }, "required": [ "page", "limit", "totalCount", "totalPages", "data" ], "type": "object" }, "CollabParticipant": { "description": "Fields describing collab participant in Developer API requests and responses.", "properties": { "characterName": { "description": "Human-readable character name for this collab participant; it is not a stable identifier.", "nullable": true, "type": "string" }, "createdAt": { "description": "UTC timestamp when this collab participant was created. Format: date-time.", "format": "date-time", "type": "string" }, "displayOrder": { "description": "Numeric display order reported for this collab participant.", "type": "integer" }, "id": { "description": "Stable identifier for the collab participant; use it in subsequent API calls instead of a display name.", "type": "integer" }, "notes": { "description": "Notes associated with this collab participant; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "placeholderImage": { "description": "Placeholder Image associated with this collab participant; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "placeholderImageDescription": { "description": "User-facing description of this collab participant; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "placeholderImageRating": { "description": "Placeholder Image Rating associated with this collab participant; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "placeholderImageSourceUrl": { "description": "URL for the placeholder image source url associated with this collab participant; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "nullable": true, "type": "string" }, "requestedAt": { "description": "UTC timestamp for the requested at transition of this collab participant. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "respondedAt": { "description": "UTC timestamp for the responded at transition of this collab participant. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "sourceTitle": { "description": "Source Title associated with this collab participant; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "status": { "description": "Current lifecycle state of this collab participant; clients should tolerate future values.", "type": "string" }, "submissions": { "description": "Ordered submissions entries included with this collab participant; an empty list means none are available.", "items": { "additionalProperties": true, "description": "Structured submissions item details for this submissions.", "type": "object" }, "type": "array" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this collab participant. Format: date-time.", "format": "date-time", "type": "string" }, "user": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "User associated with this collab participant; preserve server-returned values when passing them to another operation.", "nullable": true }, "userId": { "description": "Stable identifier for the user; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" } }, "required": [ "id", "status", "displayOrder", "submissions" ], "type": "object" }, "CollabPermissions": { "description": "Fields describing collab permissions in Developer API requests and responses.", "properties": { "canAcceptInvite": { "description": "Whether can accept invite applies to this collab permissions.", "type": "boolean" }, "canCancelOwnRequest": { "description": "Whether can cancel own request applies to this collab permissions.", "type": "boolean" }, "canDeclineInvite": { "description": "Whether can decline invite applies to this collab permissions.", "type": "boolean" }, "canEditOwnParticipant": { "description": "Whether can edit own participant applies to this collab permissions.", "type": "boolean" }, "canManage": { "description": "Whether can manage applies to this collab permissions.", "type": "boolean" }, "canRequestJoin": { "description": "Whether can request join applies to this collab permissions.", "type": "boolean" } }, "required": [ "canManage", "canRequestJoin", "canAcceptInvite", "canEditOwnParticipant", "canCancelOwnRequest", "canDeclineInvite" ], "type": "object" }, "CollabShowcase": { "description": "Fields describing collab showcase in Developer API requests and responses.", "properties": { "collab": { "$ref": "#/components/schemas/CollabShowcaseEvent" }, "entries": { "description": "Ordered entries entries included with this collab showcase; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollabShowcaseEntry" }, "type": "array" } }, "required": [ "collab", "entries" ], "type": "object" }, "CollabShowcaseEntry": { "description": "Fields describing collab showcase entry in Developer API requests and responses.", "properties": { "characterName": { "description": "Human-readable character name for this collab showcase entry; it is not a stable identifier.", "nullable": true, "type": "string" }, "entryId": { "description": "Stable identifier for the entry; use it in subsequent API calls instead of a display name.", "type": "string" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "modelTitle": { "description": "Model Title associated with this collab showcase entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "modelUrl": { "description": "URL for the model url associated with this collab showcase entry; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "nullable": true, "type": "string" }, "participantId": { "description": "Stable identifier for the participant; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "profilePicturePath": { "description": "Server-provided path for the profile picture path associated with this collab showcase entry; treat it as opaque.", "nullable": true, "type": "string" }, "profilePictureUrl": { "description": "URL for the profile picture url associated with this collab showcase entry; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "nullable": true, "type": "string" }, "profileUrl": { "description": "URL for the profile url associated with this collab showcase entry; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "nullable": true, "type": "string" }, "sourceKind": { "description": "Source Kind associated with this collab showcase entry; preserve server-returned values when passing them to another operation.", "type": "string" }, "sourceTitle": { "description": "Source Title associated with this collab showcase entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "status": { "description": "Current lifecycle state of this collab showcase entry; clients should tolerate future values.", "type": "string" }, "submissionId": { "description": "Stable identifier for the submission; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "thumbnailPath": { "description": "Server-provided path for the thumbnail path associated with this collab showcase entry; treat it as opaque.", "nullable": true, "type": "string" }, "thumbnailUrl": { "description": "URL for the thumbnail url associated with this collab showcase entry; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "nullable": true, "type": "string" }, "userId": { "description": "Stable identifier for the user; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "username": { "description": "Username associated with this collab showcase entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" } }, "required": [ "entryId", "status", "sourceKind" ], "type": "object" }, "CollabShowcaseEvent": { "description": "Fields describing collab showcase event in Developer API requests and responses.", "properties": { "id": { "description": "Stable identifier for the collab showcase event; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "releaseAt": { "description": "UTC timestamp for the release at transition of this collab showcase event. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "slug": { "description": "Slug associated with this collab showcase event; preserve server-returned values when passing them to another operation.", "type": "string" }, "status": { "description": "Current lifecycle state of this collab showcase event; clients should tolerate future values.", "type": "string" }, "title": { "description": "Display title shown to users for this collab showcase event.", "type": "string" }, "url": { "description": "URL for the url associated with this collab showcase event; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "type": "string" } }, "required": [ "id", "title", "slug", "status", "url" ], "type": "object" }, "CollabSummary": { "description": "Caller-safe summary for a live or historical collaboration. Unknown future fields must be ignored.", "properties": { "announcementEnabled": { "description": "Whether announcement enabled applies to this collab summary.", "type": "boolean" }, "availabilityCounts": { "$ref": "#/components/schemas/CollabAvailabilityCounts" }, "bannerImage": { "description": "Banner Image associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "bannerImageRating": { "description": "Banner Image Rating associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "category": { "description": "Category associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "categoryLabel": { "description": "Category Label associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "collection": { "allOf": [ { "$ref": "#/components/schemas/CollabCollectionSummary" } ], "description": "Collection associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true }, "collectionManagedByCollab": { "description": "Whether collection managed by collab applies to this collab summary.", "type": "boolean" }, "completeness": { "description": "Completeness associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "coverImages": { "description": "Ordered cover images entries included with this collab summary; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollabCoverImage" }, "type": "array" }, "createdAt": { "description": "UTC timestamp when this collab summary was created. Format: date-time.", "format": "date-time", "type": "string" }, "createdBy": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Created By associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true }, "creatorPreviews": { "description": "Ordered creator previews entries included with this collab summary; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollabCreatorPreview" }, "type": "array" }, "description": { "description": "User-facing description of this collab summary; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "discordMessageUrl": { "description": "URL for the discord message url associated with this collab summary; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "nullable": true, "type": "string" }, "evidenceLevel": { "description": "Evidence Level associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "historicalScale": { "description": "Historical Scale associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "historySummary": { "description": "History Summary associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "id": { "description": "Stable identifier for the collab summary; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "matchWindowEnd": { "description": "Match Window End associated with this collab summary; preserve server-returned values when passing them to another operation. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "matchWindowStart": { "description": "Match Window Start associated with this collab summary; preserve server-returned values when passing them to another operation. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "matchingMode": { "description": "Matching Mode associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "mode": { "description": "Mode associated with this collab summary; preserve server-returned values when passing them to another operation. Supported values: `LIVE`, `HISTORICAL`.", "enum": [ "LIVE", "HISTORICAL" ], "type": "string" }, "participantCount": { "description": "Number of participant records represented by this collab summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "releaseAt": { "description": "UTC timestamp for the release at transition of this collab summary. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "releaseEndAt": { "description": "UTC timestamp for the release end at transition of this collab summary. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "rules": { "description": "Rules associated with this collab summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "slug": { "description": "Slug associated with this collab summary; preserve server-returned values when passing them to another operation.", "type": "string" }, "status": { "description": "Current lifecycle state of this collab summary; clients should tolerate future values.", "type": "string" }, "submissionCount": { "description": "Number of submission records represented by this collab summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "title": { "description": "Display title shown to users for this collab summary.", "type": "string" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this collab summary. Format: date-time.", "format": "date-time", "type": "string" }, "visibility": { "description": "Visibility associated with this collab summary; preserve server-returned values when passing them to another operation. Supported values: `PUBLIC`, `UNLISTED`, `PRIVATE`.", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE" ], "type": "string" } }, "required": [ "id", "title", "slug", "status", "visibility", "mode", "participantCount", "submissionCount", "createdAt", "updatedAt" ], "type": "object" }, "CollectionCollaboratorSummary": { "description": "Fields describing collection collaborator summary in Developer API requests and responses.", "properties": { "id": { "description": "Stable identifier for the collection collaborator summary; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "role": { "description": "Current collection collaborator role. Clients must tolerate new roles.", "type": "string" }, "user": { "$ref": "#/components/schemas/DeveloperUserSummary" }, "userId": { "description": "Stable identifier for the user; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" } }, "required": [ "id", "role", "user" ], "type": "object" }, "CollectionContributionRequest": { "description": "Fields describing collection contribution request in Developer API requests and responses.", "properties": { "createdAt": { "description": "UTC timestamp when this collection contribution request was created. Format: date-time.", "format": "date-time", "type": "string" }, "id": { "description": "Stable identifier for the collection contribution request; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "message": { "description": "Message associated with this collection contribution request; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "respondedAt": { "description": "UTC timestamp for the responded at transition of this collection contribution request. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "respondedBy": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Responded By associated with this collection contribution request; preserve server-returned values when passing them to another operation.", "nullable": true }, "status": { "description": "Current request status. Clients must tolerate new workflow states.", "type": "string" }, "user": { "$ref": "#/components/schemas/DeveloperUserSummary" } }, "required": [ "id", "status", "message", "createdAt", "respondedAt", "user", "respondedBy" ], "type": "object" }, "CollectionDetail": { "description": "Collection detail filtered for the caller. Manager-only pendingRequests may be absent for other callers.", "properties": { "allowCollaborators": { "description": "Whether allow collaborators applies to this collection detail.", "type": "boolean" }, "collaborators": { "description": "Ordered collaborators entries included with this collection detail; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollectionCollaboratorSummary" }, "type": "array" }, "contributionRequest": { "allOf": [ { "$ref": "#/components/schemas/CollectionContributionRequest" } ], "description": "Contribution Request associated with this collection detail; preserve server-returned values when passing them to another operation.", "nullable": true }, "coverImage": { "description": "Cover Image associated with this collection detail; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "coverImageRating": { "description": "Cover Image Rating associated with this collection detail; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "createdAt": { "description": "UTC timestamp when this collection detail was created. Format: date-time.", "format": "date-time", "type": "string" }, "description": { "description": "User-facing description of this collection detail; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "favoriteCount": { "description": "Number of favorite records represented by this collection detail. Minimum: 0.", "minimum": 0, "type": "integer" }, "favoritedBy": { "description": "Ordered favorited by entries included with this collection detail; an empty list means none are available.", "items": { "description": "Structured favorited by item details for this favorited by.", "properties": { "id": { "description": "Stable identifier for the favorited by item; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "featured": { "description": "Featured associated with this collection detail; preserve server-returned values when passing them to another operation.", "type": "string" }, "id": { "description": "Stable identifier for the collection detail; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "imageItems": { "description": "Ordered image items entries included with this collection detail; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollectionImageItem" }, "type": "array" }, "itemPlacement": { "description": "Item Placement associated with this collection detail; preserve server-returned values when passing them to another operation. Supported values: `APPEND`, `PREPEND`.", "enum": [ "APPEND", "PREPEND" ], "type": "string" }, "modelItems": { "description": "Ordered model items entries included with this collection detail; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollectionModelItem" }, "type": "array" }, "name": { "description": "Human-readable name for this collection detail; it is not a stable identifier.", "type": "string" }, "owner": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Owner associated with this collection detail; preserve server-returned values when passing them to another operation.", "nullable": true }, "pagination": { "$ref": "#/components/schemas/CollectionPagination" }, "pendingRequests": { "description": "Ordered pending requests entries included with this collection detail; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollectionContributionRequest" }, "type": "array" }, "permissions": { "$ref": "#/components/schemas/CollectionPermissions" }, "selfFavorited": { "description": "Whether self favorited applies to this collection detail.", "type": "boolean" }, "slug": { "description": "Slug associated with this collection detail; preserve server-returned values when passing them to another operation.", "type": "string" }, "stats": { "$ref": "#/components/schemas/CollectionStats" }, "type": { "description": "Discriminator identifying the kind of collection detail; clients should tolerate future values. Supported values: `MODEL`, `IMAGE`.", "enum": [ "MODEL", "IMAGE" ], "type": "string" }, "visibility": { "description": "Visibility associated with this collection detail; preserve server-returned values when passing them to another operation. Supported values: `PUBLIC`, `UNLISTED`, `PRIVATE`.", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE" ], "type": "string" } }, "required": [ "id", "slug", "name", "type", "visibility", "allowCollaborators", "featured", "itemPlacement", "favoriteCount", "selfFavorited", "createdAt", "stats", "permissions", "collaborators", "contributionRequest", "modelItems", "imageItems", "pagination" ], "type": "object" }, "CollectionImageItem": { "description": "Fields describing collection image item in Developer API requests and responses.", "properties": { "addedAt": { "description": "UTC timestamp for the added at transition of this collection image item. Format: date-time.", "format": "date-time", "type": "string" }, "addedBy": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Added By associated with this collection image item; preserve server-returned values when passing them to another operation.", "nullable": true }, "id": { "description": "Stable identifier for the collection image item; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "image": { "$ref": "#/components/schemas/Image" }, "note": { "description": "Note associated with this collection image item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "order": { "description": "Numeric order reported for this collection image item.", "type": "integer" } }, "required": [ "id", "order", "addedAt", "image" ], "type": "object" }, "CollectionItemPage": { "description": "Fields describing collection item page in Developer API requests and responses.", "properties": { "nextOffset": { "description": "Numeric next offset reported for this collection item page. Minimum: 0.", "minimum": 0, "nullable": true, "type": "integer" }, "returned": { "description": "Numeric returned reported for this collection item page. Minimum: 0.", "minimum": 0, "type": "integer" }, "total": { "description": "Total number of matching records across all pages for this collection item page. Minimum: 0.", "minimum": 0, "type": "integer" } }, "required": [ "total", "returned", "nextOffset" ], "type": "object" }, "CollectionModelItem": { "description": "Fields describing collection model item in Developer API requests and responses.", "properties": { "addedAt": { "description": "UTC timestamp for the added at transition of this collection model item. Format: date-time.", "format": "date-time", "type": "string" }, "addedBy": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Added By associated with this collection model item; preserve server-returned values when passing them to another operation.", "nullable": true }, "id": { "description": "Stable identifier for the collection model item; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "model": { "$ref": "#/components/schemas/Model" }, "note": { "description": "Note associated with this collection model item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "order": { "description": "Numeric order reported for this collection model item.", "type": "integer" } }, "required": [ "id", "order", "addedAt", "model" ], "type": "object" }, "CollectionPage": { "description": "Fields describing collection page in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this collection page; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollectionSummary" }, "type": "array" }, "limit": { "description": "Maximum number of records requested or returned in one page of this collection page. Minimum: 1.", "minimum": 1, "type": "integer" }, "page": { "description": "One-based result page requested or returned for this collection page. Minimum: 1.", "minimum": 1, "type": "integer" }, "totalCount": { "description": "Total number of matching records across all pages for this collection page. Minimum: 0.", "minimum": 0, "type": "integer" }, "totalPages": { "description": "Total number of pages available at the current page size for this collection page. Minimum: 0.", "minimum": 0, "type": "integer" } }, "required": [ "page", "limit", "totalCount", "totalPages", "data" ], "type": "object" }, "CollectionPagination": { "description": "Fields describing collection pagination in Developer API requests and responses.", "properties": { "images": { "$ref": "#/components/schemas/CollectionItemPage" }, "models": { "$ref": "#/components/schemas/CollectionItemPage" } }, "required": [ "models", "images" ], "type": "object" }, "CollectionPermissions": { "description": "Fields describing collection permissions in Developer API requests and responses.", "properties": { "canContribute": { "description": "Whether can contribute applies to this collection permissions.", "type": "boolean" }, "canManageCollaborators": { "description": "Whether can manage collaborators applies to this collection permissions.", "type": "boolean" }, "isCollaborator": { "description": "Whether is collaborator applies to this collection permissions.", "type": "boolean" }, "isOwner": { "description": "Whether is owner applies to this collection permissions.", "type": "boolean" } }, "required": [ "isOwner", "canContribute", "isCollaborator", "canManageCollaborators" ], "type": "object" }, "CollectionStats": { "description": "Fields describing collection stats in Developer API requests and responses.", "properties": { "imageCount": { "description": "Number of image records represented by this collection stats. Minimum: 0.", "minimum": 0, "type": "integer" }, "lastUpdated": { "description": "Last Updated associated with this collection stats; preserve server-returned values when passing them to another operation. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "modelCount": { "description": "Number of model records represented by this collection stats. Minimum: 0.", "minimum": 0, "type": "integer" }, "totalItems": { "description": "Numeric total items reported for this collection stats. Minimum: 0.", "minimum": 0, "type": "integer" } }, "required": [ "modelCount", "imageCount", "totalItems", "lastUpdated" ], "type": "object" }, "CollectionSummary": { "description": "Caller-safe collection summary. Integrations must ignore new presentation and aggregate fields.", "properties": { "allowCollaborators": { "description": "Whether allow collaborators applies to this collection summary.", "type": "boolean" }, "collaboratorCount": { "description": "Number of collaborator records represented by this collection summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "collaborators": { "description": "Ordered collaborators entries included with this collection summary; an empty list means none are available.", "items": { "$ref": "#/components/schemas/CollectionCollaboratorSummary" }, "type": "array" }, "coverImage": { "description": "Cover Image associated with this collection summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "coverImageRating": { "description": "Cover Image Rating associated with this collection summary; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "createdAt": { "description": "UTC timestamp when this collection summary was created. Format: date-time.", "format": "date-time", "type": "string" }, "description": { "description": "User-facing description of this collection summary; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "favoriteCount": { "description": "Number of favorite records represented by this collection summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "favoritedBy": { "description": "Ordered favorited by entries included with this collection summary; an empty list means none are available.", "items": { "description": "Structured favorited by item details for this favorited by.", "properties": { "id": { "description": "Stable identifier for the favorited by item; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" } }, "required": [ "id" ], "type": "object" }, "type": "array" }, "featured": { "description": "Featured associated with this collection summary; preserve server-returned values when passing them to another operation.", "type": "string" }, "id": { "description": "Stable identifier for the collection summary; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "imageCount": { "description": "Number of image records represented by this collection summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "itemCount": { "description": "Number of item records represented by this collection summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "itemPlacement": { "description": "Item Placement associated with this collection summary; preserve server-returned values when passing them to another operation. Supported values: `APPEND`, `PREPEND`.", "enum": [ "APPEND", "PREPEND" ], "type": "string" }, "lastUpdated": { "description": "Last Updated associated with this collection summary; preserve server-returned values when passing them to another operation. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "modelCount": { "description": "Number of model records represented by this collection summary. Minimum: 0.", "minimum": 0, "type": "integer" }, "name": { "description": "Human-readable name for this collection summary; it is not a stable identifier.", "type": "string" }, "owner": { "allOf": [ { "$ref": "#/components/schemas/DeveloperUserSummary" } ], "description": "Owner associated with this collection summary; preserve server-returned values when passing them to another operation.", "nullable": true }, "selfFavorited": { "description": "Whether self favorited applies to this collection summary.", "type": "boolean" }, "slug": { "description": "Slug associated with this collection summary; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of collection summary; clients should tolerate future values. Supported values: `MODEL`, `IMAGE`.", "enum": [ "MODEL", "IMAGE" ], "type": "string" }, "visibility": { "description": "Visibility associated with this collection summary; preserve server-returned values when passing them to another operation. Supported values: `PUBLIC`, `UNLISTED`, `PRIVATE`.", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE" ], "type": "string" } }, "required": [ "id", "slug", "name", "type", "visibility", "allowCollaborators", "featured", "favoriteCount", "selfFavorited", "itemPlacement", "collaborators", "itemCount", "modelCount", "imageCount", "collaboratorCount", "createdAt" ], "type": "object" }, "CreateModelVersionChunkUploadRequest": { "additionalProperties": false, "description": "Fields describing create model version chunk upload request in Developer API requests and responses.", "properties": { "aboutThisVersion": { "description": "Optional version notes.", "example": "Improved natural-light rendering.", "maxLength": 1000, "type": "string" }, "activationTags": { "description": "Optional comma-separated activation tags.", "example": "landscape, natural light", "maxLength": 8000, "type": "string" }, "baseModel": { "description": "Optional base-model label.", "example": "SDXL 1.0", "maxLength": 120, "type": "string" }, "chunkSize": { "default": 8388608, "description": "Optional positive preferred chunk length in bytes. The server clamps it to the effective range 8388608–90000000 bytes; the default is 8388608 bytes. Always split the file using the `chunkSize` returned in the created session.", "example": 8388608, "format": "int64", "minimum": 1, "type": "integer", "x-effective-maximum": 90000000, "x-effective-minimum": 8388608 }, "fileName": { "description": "Original model-file name. Its extension must be allowed for the target model type.", "example": "landscape-v2.safetensors", "minLength": 1, "type": "string" }, "fileSize": { "description": "Exact total file length in bytes. Maximum: 536870912 bytes (512 MiB).", "example": 16777216, "format": "int64", "maximum": 536870912, "minimum": 1, "type": "integer" }, "modelId": { "description": "ID of the model that will own the new draft version.", "example": 42, "minimum": 1, "type": "integer" }, "supporterEarlyAccessEnabled": { "default": true, "description": "Set false to opt the new hosted version out of the 72-hour supporter early-access window.", "type": "boolean" }, "versionName": { "description": "Optional display name for the new version.", "example": "Landscape v2", "maxLength": 100, "type": "string" } }, "required": [ "modelId", "fileName", "fileSize" ], "type": "object" }, "CreatorStatsAppliedRange": { "description": "Structured applied range details for this creator stats response.", "properties": { "end": { "description": "Inclusive applied range end.", "format": "date-time", "type": "string" }, "start": { "description": "Inclusive applied range start.", "format": "date-time", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "CreatorStatsRangeBounds": { "description": "Structured range bounds details for this creator stats response.", "properties": { "max": { "description": "Latest available timestamp.", "format": "date-time", "type": "string" }, "min": { "description": "Earliest available timestamp.", "format": "date-time", "type": "string" } }, "required": [ "min", "max" ], "type": "object" }, "CreatorStatsResponse": { "description": "Aggregated creator engagement and download statistics for the applied time range.", "properties": { "appliedRange": { "$ref": "#/components/schemas/CreatorStatsAppliedRange" }, "comments": { "description": "Numeric comments reported for this creator stats response.", "type": "integer" }, "downloadEventsTotal": { "description": "Download events in the applied range; null when advanced download analytics are unavailable.", "nullable": true, "type": "integer" }, "downloadPerformance": { "description": "Structured download performance details for this creator stats response.", "properties": { "returningDownloaderRate": { "description": "Ratio from zero through one.", "format": "double", "nullable": true, "type": "number" }, "returningDownloaders": { "description": "Numeric returning downloaders reported for this download performance.", "nullable": true, "type": "integer" } }, "required": [ "returningDownloaders", "returningDownloaderRate" ], "type": "object" }, "downloadSeries": { "description": "Ordered download series entries included with this creator stats response; an empty list means none are available.", "items": { "description": "Structured download series item details for this download series.", "properties": { "count": { "description": "Compatibility alias for events.", "type": "integer" }, "date": { "description": "Date associated with this download series item; preserve server-returned values when passing them to another operation. Format: date.", "format": "date", "type": "string" }, "events": { "description": "Numeric events reported for this download series item.", "type": "integer" }, "uniqueDownloaders": { "description": "Numeric unique downloaders reported for this download series item.", "type": "integer" } }, "required": [ "date", "events", "uniqueDownloaders", "count" ], "type": "object" }, "type": "array" }, "downloadsTotal": { "description": "Compatibility alias for downloadEventsTotal.", "nullable": true, "type": "integer" }, "favorites": { "description": "Structured favorites details for this creator stats response.", "properties": { "articles": { "description": "Numeric articles reported for this favorites.", "type": "integer" }, "models": { "description": "Numeric models reported for this favorites.", "type": "integer" } }, "required": [ "models", "articles" ], "type": "object" }, "followers": { "description": "Numeric followers reported for this creator stats response.", "type": "integer" }, "meta": { "description": "Structured meta details for this creator stats response.", "properties": { "accessTier": { "description": "Current access tier. Known values are STANDARD, SUPPORTER, and STAFF; clients must tolerate additions.", "type": "string" }, "advancedAccess": { "description": "Whether advanced access applies to this meta.", "type": "boolean" }, "cache": { "description": "Structured cache details for this meta.", "properties": { "expiresAt": { "description": "UTC timestamp for the expires at transition of this cache. Format: date-time.", "format": "date-time", "type": "string" }, "hit": { "description": "Whether hit applies to this cache.", "type": "boolean" }, "ttlMs": { "description": "Numeric ttl ms reported for this cache.", "type": "integer" } }, "required": [ "hit", "expiresAt", "ttlMs" ], "type": "object" }, "maxWindowDays": { "description": "Numeric max window days reported for this meta.", "type": "integer" }, "rangeClamped": { "description": "Whether range clamped applies to this meta.", "type": "boolean" }, "standardWindowDays": { "description": "Numeric standard window days reported for this meta.", "type": "integer" } }, "required": [ "maxWindowDays", "rangeClamped", "accessTier", "advancedAccess", "standardWindowDays", "cache" ], "type": "object" }, "rangeBounds": { "$ref": "#/components/schemas/CreatorStatsRangeBounds" }, "reactions": { "description": "Structured reactions details for this creator stats response.", "properties": { "dislikes": { "description": "Numeric dislikes reported for this reactions.", "type": "integer" }, "hearts": { "description": "Numeric hearts reported for this reactions.", "type": "integer" }, "likes": { "description": "Numeric likes reported for this reactions.", "type": "integer" } }, "required": [ "hearts", "likes", "dislikes" ], "type": "object" }, "topModels": { "description": "Ordered top models entries included with this creator stats response; an empty list means none are available.", "items": { "description": "Structured top models item details for this top models.", "properties": { "downloads": { "description": "Compatibility alias for events.", "type": "integer" }, "events": { "description": "Numeric events reported for this top models item.", "type": "integer" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "type": "integer" }, "title": { "description": "Display title shown to users for this top models item.", "type": "string" }, "uniqueDownloaders": { "description": "Numeric unique downloaders reported for this top models item.", "type": "integer" } }, "required": [ "modelId", "title", "events", "uniqueDownloaders", "downloads" ], "type": "object" }, "type": "array" }, "uniqueDownloadersTotal": { "description": "Distinct tracked downloaders in the applied range.", "nullable": true, "type": "integer" }, "uniqueDownloads": { "description": "Compatibility alias for uniqueDownloadersTotal.", "nullable": true, "type": "integer" } }, "required": [ "downloadEventsTotal", "uniqueDownloadersTotal", "downloadsTotal", "uniqueDownloads", "downloadPerformance", "downloadSeries", "rangeBounds", "appliedRange", "reactions", "favorites", "comments", "followers", "topModels", "meta" ], "type": "object" }, "DeveloperArticleMutationResponse": { "properties": { "article": { "$ref": "#/components/schemas/Article" }, "message": { "description": "Human-readable confirmation of the completed article mutation; use the HTTP status and article payload for logic.", "type": "string" } }, "required": [ "message", "article" ], "type": "object" }, "DeveloperAttachedImagesResponse": { "properties": { "imageIds": { "example": [ 108 ], "items": { "type": "integer" }, "type": "array" }, "imageOrder": { "example": [ 107, 108 ], "items": { "type": "integer" }, "type": "array" }, "message": { "example": "Existing Discord images attached to version.", "type": "string" }, "skippedAlreadyAttachedIds": { "example": [ 107 ], "items": { "type": "integer" }, "type": "array" } }, "required": [ "message", "imageIds", "skippedAlreadyAttachedIds", "imageOrder" ], "type": "object" }, "DeveloperChatAttachment": { "properties": { "bytes": { "example": 182430, "minimum": 0, "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "durationMs": { "example": null, "minimum": 0, "nullable": true, "type": "integer" }, "filePath": { "description": "Caller-bound signed media URL or stable relative path. Clients must not persist signed query parameters.", "example": "/uploads/chat/thread-81/image.webp?token=temporary", "type": "string" }, "height": { "example": 1024, "minimum": 1, "nullable": true, "type": "integer" }, "id": { "example": 901, "minimum": 1, "type": "integer" }, "kind": { "description": "Attachment media kind. Clients must tolerate future values.", "example": "IMAGE", "type": "string" }, "mimeType": { "example": "image/webp", "type": "string" }, "width": { "example": 1024, "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "id", "kind", "filePath", "mimeType", "bytes", "width", "height", "durationMs", "createdAt" ], "type": "object" }, "DeveloperChatAvatarResponse": { "properties": { "imagePath": { "description": "Caller-bound signed group-avatar URL. Clients must not persist signed query parameters.", "example": "/uploads/chat/group-81.webp?token=temporary", "type": "string" } }, "required": [ "imagePath" ], "type": "object" }, "DeveloperChatBadge": { "properties": { "icon": { "example": "ri-brush-line", "nullable": true, "type": "string" }, "id": { "example": 7, "minimum": 1, "type": "integer" }, "name": { "example": "Creator", "type": "string" }, "type": { "description": "Badge category. Clients must tolerate future values.", "example": "CREATOR", "type": "string" } }, "required": [ "id", "name", "icon", "type" ], "type": "object" }, "DeveloperChatDirectStateResponse": { "properties": { "directStatus": { "example": "PENDING", "nullable": true, "type": "string" }, "threadId": { "example": 81, "minimum": 1, "type": "integer" } }, "required": [ "threadId" ], "type": "object" }, "DeveloperChatLinkPreview": { "properties": { "creator": { "example": "aurora", "nullable": true, "type": "string" }, "description": { "example": "A visibility-checked preview.", "nullable": true, "type": "string" }, "domain": { "example": "example.com", "nullable": true, "type": "string" }, "faviconUrl": { "format": "uri", "nullable": true, "type": "string" }, "id": { "example": 108, "minimum": 1, "nullable": true, "type": "integer" }, "imagePath": { "example": "/uploads/images/108.thumbnail.webp", "nullable": true, "type": "string" }, "imageUrl": { "format": "uri", "nullable": true, "type": "string" }, "kind": { "description": "Preview resource kind. Clients must tolerate future values.", "example": "IMAGE", "type": "string" }, "originalDomain": { "example": "example.com", "nullable": true, "type": "string" }, "originalUrl": { "format": "uri", "nullable": true, "type": "string" }, "siteName": { "example": "Example", "nullable": true, "type": "string" }, "title": { "example": "Evening portrait", "nullable": true, "type": "string" }, "url": { "example": "https://arcenciel.io/images/108", "format": "uri", "type": "string" }, "wasShortened": { "example": false, "type": "boolean" } }, "required": [ "kind", "url" ], "type": "object" }, "DeveloperChatMessage": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/DeveloperChatAttachment" }, "type": "array" }, "content": { "example": "Here is the finished render, @aurora.", "nullable": true, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "example": 501, "minimum": 1, "type": "integer" }, "mentions": { "additionalProperties": { "minimum": 1, "type": "integer" }, "example": { "aurora": 42 }, "nullable": true, "type": "object" }, "reactions": { "items": { "$ref": "#/components/schemas/DeveloperChatReaction" }, "type": "array" }, "replyTo": { "allOf": [ { "$ref": "#/components/schemas/DeveloperChatReply" } ], "nullable": true }, "sender": { "$ref": "#/components/schemas/DeveloperChatUser" }, "senderId": { "example": 42, "minimum": 1, "type": "integer" }, "threadId": { "example": 81, "minimum": 1, "type": "integer" } }, "required": [ "id", "threadId", "senderId", "mentions", "replyTo", "content", "createdAt", "attachments", "reactions" ], "type": "object" }, "DeveloperChatMessageListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DeveloperChatMessage" }, "type": "array" }, "limit": { "example": 50, "maximum": 200, "minimum": 1, "type": "integer" }, "nextCursor": { "example": 450, "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "data", "nextCursor", "limit" ], "type": "object" }, "DeveloperChatMessageSummary": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/DeveloperChatAttachment" }, "type": "array" }, "content": { "example": "The new render is ready.", "nullable": true, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "example": 501, "minimum": 1, "type": "integer" }, "senderId": { "example": 42, "minimum": 1, "type": "integer" } }, "required": [ "id", "senderId", "content", "createdAt", "attachments" ], "type": "object" }, "DeveloperChatOkResponse": { "properties": { "ok": { "enum": [ true ], "example": true, "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "DeveloperChatParticipant": { "properties": { "archivedAt": { "example": null, "format": "date-time", "nullable": true, "type": "string" }, "role": { "description": "Conversation participant role. Clients must tolerate future values.", "example": "MEMBER", "type": "string" }, "state": { "description": "Conversation participant state. Clients must tolerate future values.", "example": "ACTIVE", "type": "string" }, "user": { "$ref": "#/components/schemas/DeveloperChatUser" }, "userId": { "example": 18, "minimum": 1, "type": "integer" } }, "required": [ "userId", "role", "state", "archivedAt", "user" ], "type": "object" }, "DeveloperChatPresenceEntry": { "properties": { "lastSeenAt": { "format": "date-time", "nullable": true, "type": "string" }, "online": { "example": true, "type": "boolean" } }, "required": [ "online", "lastSeenAt" ], "type": "object" }, "DeveloperChatPresenceResponse": { "properties": { "data": { "additionalProperties": { "$ref": "#/components/schemas/DeveloperChatPresenceEntry" }, "description": "Presence entries keyed by the requested decimal user identifier.", "example": { "42": { "lastSeenAt": "2026-08-07T10:00:00.000Z", "online": true } }, "type": "object" } }, "required": [ "data" ], "type": "object" }, "DeveloperChatReaction": { "properties": { "count": { "example": 2, "minimum": 0, "type": "integer" }, "emoteName": { "example": "heart", "pattern": "^[a-z0-9_]{1,32}$", "type": "string" }, "me": { "description": "Whether the authenticated caller contributed this reaction.", "example": true, "type": "boolean" }, "users": { "items": { "$ref": "#/components/schemas/DeveloperChatUser" }, "type": "array" } }, "required": [ "emoteName", "count", "users" ], "type": "object" }, "DeveloperChatReactionResponse": { "properties": { "messageId": { "example": 501, "minimum": 1, "type": "integer" }, "reactions": { "items": { "$ref": "#/components/schemas/DeveloperChatReaction" }, "type": "array" } }, "required": [ "messageId", "reactions" ], "type": "object" }, "DeveloperChatReply": { "properties": { "content": { "example": "Can you share the final image?", "nullable": true, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "example": 498, "minimum": 1, "type": "integer" }, "sender": { "$ref": "#/components/schemas/DeveloperChatUser" }, "senderId": { "example": 18, "minimum": 1, "type": "integer" } }, "required": [ "id", "senderId", "content", "createdAt" ], "type": "object" }, "DeveloperChatRequestResponse": { "description": "An existing direct-state summary, a newly or previously resolved thread, or a newly created message when the convenience route sends into an active thread.", "oneOf": [ { "$ref": "#/components/schemas/DeveloperChatDirectStateResponse" }, { "$ref": "#/components/schemas/DeveloperChatThread" }, { "$ref": "#/components/schemas/DeveloperChatMessage" } ] }, "DeveloperChatThread": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "createdById": { "example": 42, "minimum": 1, "type": "integer" }, "directRequesterId": { "example": null, "minimum": 1, "nullable": true, "type": "integer" }, "directStatus": { "example": null, "nullable": true, "type": "string" }, "hasUnread": { "example": true, "type": "boolean" }, "id": { "example": 81, "minimum": 1, "type": "integer" }, "imagePath": { "example": "/uploads/chat/group-81.webp?token=temporary", "nullable": true, "type": "string" }, "kind": { "description": "Conversation kind. Clients must tolerate future values.", "example": "GROUP", "type": "string" }, "lastMessage": { "allOf": [ { "$ref": "#/components/schemas/DeveloperChatMessageSummary" } ], "nullable": true }, "lastMessageAt": { "format": "date-time", "nullable": true, "type": "string" }, "participants": { "items": { "$ref": "#/components/schemas/DeveloperChatParticipant" }, "type": "array" }, "title": { "example": "Release artwork", "maxLength": 80, "nullable": true, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "viewer": { "$ref": "#/components/schemas/DeveloperChatViewerState" } }, "required": [ "id", "kind", "title", "imagePath", "createdById", "directStatus", "directRequesterId", "lastMessageAt", "viewer", "participants", "lastMessage", "hasUnread", "createdAt", "updatedAt" ], "type": "object" }, "DeveloperChatThreadListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DeveloperChatThread" }, "type": "array" }, "limit": { "example": 30, "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "data", "limit" ], "type": "object" }, "DeveloperChatTitleResponse": { "properties": { "title": { "example": "Release artwork", "maxLength": 80, "nullable": true, "type": "string" } }, "required": [ "title" ], "type": "object" }, "DeveloperChatUnreadCountResponse": { "properties": { "count": { "example": 3, "minimum": 0, "type": "integer" } }, "required": [ "count" ], "type": "object" }, "DeveloperChatUser": { "properties": { "badges": { "items": { "$ref": "#/components/schemas/DeveloperChatBadge" }, "type": "array" }, "id": { "example": 42, "minimum": 1, "type": "integer" }, "namecardPreference": { "example": "aurora", "nullable": true, "type": "string" }, "profilePicture": { "example": "/uploads/profile/42.webp", "nullable": true, "type": "string" }, "profilePictureRating": { "example": "SAFE", "nullable": true, "type": "string" }, "role": { "description": "Current public account role. Clients must tolerate future values.", "example": "CREATOR", "type": "string" }, "username": { "example": "aurora", "minLength": 1, "type": "string" } }, "required": [ "id", "username", "profilePicture", "profilePictureRating", "role", "namecardPreference", "badges" ], "type": "object" }, "DeveloperChatViewerState": { "properties": { "archivedAt": { "example": null, "format": "date-time", "nullable": true, "type": "string" }, "lastReadAt": { "format": "date-time", "nullable": true, "type": "string" }, "lastReadMessageId": { "example": 498, "minimum": 1, "nullable": true, "type": "integer" }, "role": { "example": "MEMBER", "nullable": true, "type": "string" }, "state": { "example": "ACTIVE", "nullable": true, "type": "string" } }, "required": [ "role", "state", "archivedAt", "lastReadAt", "lastReadMessageId" ], "type": "object" }, "DeveloperCollabParticipantResponse": { "properties": { "participant": { "$ref": "#/components/schemas/CollabParticipant" } }, "required": [ "participant" ], "type": "object" }, "DeveloperCollabPlaceholderUploadResponse": { "properties": { "participant": { "$ref": "#/components/schemas/CollabParticipant" }, "path": { "example": "uploads/collabs/placeholder.webp", "type": "string" }, "rating": { "description": "Safety rating returned by the media pipeline.", "example": "safe", "type": "string" } }, "required": [ "path", "rating", "participant" ], "type": "object" }, "DeveloperCollectionContributionDecisionResponse": { "properties": { "collaborator": { "allOf": [ { "$ref": "#/components/schemas/CollectionCollaboratorSummary" } ], "nullable": true }, "request": { "$ref": "#/components/schemas/CollectionContributionRequest" } }, "required": [ "request", "collaborator" ], "type": "object" }, "DeveloperCollectionCoverUploadResponse": { "properties": { "path": { "example": "uploads/collections/cover.webp", "type": "string" }, "rating": { "description": "Safety rating returned by the media pipeline.", "example": "safe", "type": "string" } }, "required": [ "path", "rating" ], "type": "object" }, "DeveloperCollectionIdentity": { "properties": { "id": { "example": 84, "minimum": 1, "type": "integer" }, "slug": { "example": "portrait-workflow", "minLength": 1, "type": "string" } }, "required": [ "id", "slug" ], "type": "object" }, "DeveloperCollectionItemsMutationResponse": { "properties": { "added": { "example": [ 52, 61 ], "items": { "type": "integer" }, "type": "array" }, "addedCount": { "example": 2, "minimum": 0, "type": "integer" }, "collectionId": { "example": 84, "minimum": 1, "type": "integer" }, "createdItemIds": { "example": [ 701, 702 ], "items": { "type": "integer" }, "type": "array" }, "duplicate": { "example": [ 18 ], "items": { "type": "integer" }, "type": "array" }, "duplicateCount": { "example": 1, "minimum": 0, "type": "integer" }, "missing": { "example": [ 999999 ], "items": { "type": "integer" }, "type": "array" }, "missingCount": { "example": 1, "minimum": 0, "type": "integer" }, "type": { "description": "Current values are MODEL and IMAGE; clients must tolerate additions.", "example": "MODEL", "type": "string" } }, "required": [ "collectionId", "type", "added", "duplicate", "missing", "createdItemIds", "addedCount", "duplicateCount", "missingCount" ], "type": "object" }, "DeveloperComment": { "properties": { "author": { "$ref": "#/components/schemas/DeveloperUserSummary" }, "authorId": { "example": 42, "type": "integer" }, "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" }, "createdAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "example": 912, "type": "integer" }, "isDeleted": { "example": false, "type": "boolean" }, "mentions": { "additionalProperties": true, "nullable": true, "type": "object" }, "parentCommentId": { "example": null, "nullable": true, "type": "integer" }, "targetId": { "example": 108, "type": "integer" }, "targetType": { "description": "Resource domain containing the comment.", "example": "IMAGE", "type": "string" }, "threadId": { "example": 912, "nullable": true, "type": "integer" }, "updatedAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "id", "authorId", "content", "targetType", "targetId", "isDeleted", "createdAt", "updatedAt" ], "type": "object" }, "DeveloperCommentMutationResponse": { "properties": { "comment": { "$ref": "#/components/schemas/DeveloperComment" }, "message": { "example": "Comment created", "type": "string" } }, "required": [ "message", "comment" ], "type": "object" }, "DeveloperDataExport": { "properties": { "audit": { "items": { "description": "Redacted audit record for the authenticated account.", "type": "object" }, "type": "array" }, "comments": { "items": { "$ref": "#/components/schemas/DeveloperComment" }, "type": "array" }, "profile": { "$ref": "#/components/schemas/SelfProfile" }, "uploads": { "$ref": "#/components/schemas/Uploads" } }, "required": [ "profile", "uploads", "comments", "audit" ], "type": "object" }, "DeveloperDiscordImageCandidate": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "disabledReason": { "example": null, "nullable": true, "type": "string" }, "dislikeCount": { "example": 0, "minimum": 0, "type": "integer" }, "fileName": { "example": "portrait.webp", "nullable": true, "type": "string" }, "filePath": { "example": "uploads/images/portrait.webp", "type": "string" }, "heartCount": { "example": 2, "minimum": 0, "type": "integer" }, "height": { "example": 1024, "nullable": true, "type": "integer" }, "id": { "example": 108, "minimum": 1, "type": "integer" }, "isAlreadyAttached": { "example": false, "type": "boolean" }, "isAttachable": { "example": true, "type": "boolean" }, "likeCount": { "example": 4, "minimum": 0, "type": "integer" }, "matchedHashes": { "example": [ "0123456789abcdef" ], "items": { "type": "string" }, "type": "array" }, "title": { "example": "Portrait sample", "nullable": true, "type": "string" }, "uploadSource": { "example": "discord", "nullable": true, "type": "string" }, "uploadedViaDiscord": { "example": true, "type": "boolean" }, "variants": { "additionalProperties": true, "nullable": true, "type": "object" }, "width": { "example": 1024, "nullable": true, "type": "integer" } }, "required": [ "id", "matchedHashes", "isAlreadyAttached", "isAttachable", "disabledReason" ], "type": "object" }, "DeveloperDiscordImageCandidatesResponse": { "properties": { "alreadyAttachedCount": { "example": 0, "minimum": 0, "type": "integer" }, "attachableCount": { "example": 1, "minimum": 0, "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/DeveloperDiscordImageCandidate" }, "type": "array" }, "totalFound": { "example": 1, "minimum": 0, "type": "integer" } }, "required": [ "totalFound", "attachableCount", "alreadyAttachedCount", "items" ], "type": "object" }, "DeveloperDownloadHistoryEntry": { "properties": { "createdAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "example": 8001, "type": "integer" }, "userId": { "example": 42, "type": "integer" }, "version": { "allOf": [ { "$ref": "#/components/schemas/Version" } ], "nullable": true }, "versionId": { "example": 321, "type": "integer" }, "viaLink": { "example": false, "type": "boolean" } }, "required": [ "id", "userId", "versionId", "createdAt", "viaLink" ], "type": "object" }, "DeveloperFeedback": { "properties": { "assignee": { "allOf": [ { "$ref": "#/components/schemas/DeveloperFeedbackActor" } ], "nullable": true }, "attachments": { "items": { "$ref": "#/components/schemas/DeveloperFeedbackAttachment" }, "type": "array" }, "category": { "description": "Feedback category. Known values: BUG, FEATURE, UX, PERFORMANCE, MODERATION, OTHER. Clients must tolerate future values.", "example": "BUG", "type": "string" }, "contactDiscord": { "example": "aurora", "maxLength": 120, "nullable": true, "type": "string" }, "createdAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "description": { "example": "The browser remains at 99 percent after the final chunk was transferred.", "maxLength": 4000, "minLength": 20, "type": "string" }, "internalNotes": { "description": "Staff-only note. This is always null for the reporter and must never be inferred from absence.", "example": null, "nullable": true, "type": "string" }, "priority": { "description": "Feedback triage priority. Known values: LOW, MEDIUM, HIGH. Clients must tolerate future values.", "example": "MEDIUM", "type": "string" }, "publicId": { "example": "FB-9A2C13", "pattern": "^FB-[A-Z0-9-]+$", "type": "string" }, "reporter": { "allOf": [ { "$ref": "#/components/schemas/DeveloperFeedbackActor" } ], "nullable": true }, "resolvedAt": { "example": null, "format": "date-time", "nullable": true, "type": "string" }, "sourcePath": { "example": "/models/upload", "nullable": true, "type": "string" }, "sourceUrl": { "example": "https://arcenciel.io/models/upload", "format": "uri", "nullable": true, "type": "string" }, "status": { "description": "Feedback state. Known values: OPEN, TRIAGED, IN_PROGRESS, RESOLVED, DECLINED, DUPLICATE. Clients must tolerate future values.", "example": "OPEN", "type": "string" }, "title": { "example": "Upload progress stalls near completion", "maxLength": 140, "minLength": 5, "type": "string" }, "updatedAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "updatedBy": { "allOf": [ { "$ref": "#/components/schemas/DeveloperFeedbackActor" } ], "nullable": true } }, "required": [ "publicId", "category", "status", "priority", "title", "description", "sourceUrl", "sourcePath", "contactDiscord", "internalNotes", "reporter", "assignee", "updatedBy", "createdAt", "updatedAt", "resolvedAt", "attachments" ], "type": "object" }, "DeveloperFeedbackActor": { "properties": { "id": { "example": 42, "minimum": 1, "type": "integer" }, "username": { "example": "aurora", "minLength": 1, "type": "string" } }, "required": [ "id", "username" ], "type": "object" }, "DeveloperFeedbackAttachment": { "properties": { "downloadPath": { "example": "/api/feedback/FB-9A2C13/attachments/cm4attachment01", "type": "string" }, "expiresAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "fileName": { "example": "console-log.txt", "type": "string" }, "id": { "example": "cm4attachment01", "minLength": 1, "type": "string" }, "mimeType": { "example": "text/plain", "type": "string" }, "sizeBytes": { "example": 1842, "minimum": 0, "type": "integer" } }, "required": [ "id", "fileName", "mimeType", "sizeBytes", "expiresAt", "downloadPath" ], "type": "object" }, "DeveloperFeedbackDeleteResponse": { "properties": { "message": { "example": "Feedback deleted.", "type": "string" } }, "required": [ "message" ], "type": "object" }, "DeveloperIllegalContentNoticeCreateResponse": { "properties": { "accessCode": { "description": "One-time guest lookup secret. Null for authenticated reporters; store it securely and never log it.", "example": null, "nullable": true, "type": "string" }, "lookupUrl": { "example": "https://arcenciel.io/report-illegal-content?case=ICN-9A2C13", "format": "uri", "type": "string" }, "publicId": { "example": "ICN-9A2C13", "type": "string" }, "status": { "description": "Current case state. Known values: SUBMITTED, IN_REVIEW, ACTION_TAKEN, NO_ACTION, ESCALATED. Clients must tolerate future values.", "example": "SUBMITTED", "type": "string" }, "targetLabel": { "example": "Evening portrait", "nullable": true, "type": "string" }, "targetType": { "description": "Resolved notice target type. Known values: GENERIC_URL, MODEL, IMAGE, VIDEO, USER_PROFILE, AVATAR, BANNER, ARTICLE, COMMENT, COLLECTION. Clients must tolerate future values.", "example": "IMAGE", "type": "string" } }, "required": [ "publicId", "lookupUrl", "accessCode", "status", "targetType", "targetLabel" ], "type": "object" }, "DeveloperIllegalContentNoticeDetail": { "allOf": [ { "$ref": "#/components/schemas/DeveloperIllegalContentNoticeSummary" }, { "properties": { "affectedUserMessage": { "description": "Present only for the affected owner or staff.", "nullable": true, "type": "string" }, "canRequestReview": { "example": false, "type": "boolean" }, "decisionReason": { "example": null, "nullable": true, "type": "string" }, "description": { "example": "The published image contains personal information without consent.", "minLength": 20, "type": "string" }, "evidence": { "example": "The attached screenshot marks the relevant area.", "nullable": true, "type": "string" }, "evidenceAttachments": { "items": { "$ref": "#/components/schemas/DeveloperNoticeEvidenceAttachment" }, "type": "array" }, "jurisdiction": { "example": "DE", "nullable": true, "type": "string" }, "legalBasis": { "example": "Applicable national privacy law.", "nullable": true, "type": "string" }, "reporterMessage": { "description": "Present only for the reporter or staff.", "nullable": true, "type": "string" }, "reviewRequestMessage": { "example": null, "nullable": true, "type": "string" }, "reviewedBy": { "allOf": [ { "$ref": "#/components/schemas/DeveloperNoticeReviewer" } ], "nullable": true }, "targetId": { "example": 108, "minimum": 1, "nullable": true, "type": "integer" }, "targetTypeHint": { "description": "Resolved notice target type. Known values: GENERIC_URL, MODEL, IMAGE, VIDEO, USER_PROFILE, AVATAR, BANNER, ARTICLE, COMMENT, COLLECTION. Clients must tolerate future values.", "example": "IMAGE", "nullable": true, "type": "string" } }, "required": [ "targetTypeHint", "targetId", "legalBasis", "description", "evidence", "evidenceAttachments", "jurisdiction", "decisionReason", "reviewRequestMessage", "canRequestReview" ], "type": "object" } ] }, "DeveloperIllegalContentNoticeSummary": { "properties": { "acknowledgedAt": { "example": null, "format": "date-time", "nullable": true, "type": "string" }, "category": { "description": "Alleged illegal-content category. Known values: SCAM_OR_FRAUD, COUNTERFEIT_OR_ILLEGAL_GOODS, CHILD_SAFETY, SEXUAL_CONTENT_INVOLVING_MINORS, ILLEGAL_HATE_OR_HARASSMENT, PRIVACY_OR_DOOXING, IMPERSONATION_OR_DECEPTION, VIOLENCE_OR_THREATS, INTELLECTUAL_PROPERTY, OTHER_ILLEGAL_CONTENT. Clients must tolerate future values.", "example": "PRIVACY_OR_DOOXING", "type": "string" }, "createdAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "decidedAt": { "example": null, "format": "date-time", "nullable": true, "type": "string" }, "decisionAction": { "description": "Recorded moderation action. Known values: NONE, REMOVE_CONTENT, RESTRICT_ACCESS, AGE_RESTRICT, GEO_BLOCK, SUSPEND_ACCOUNT, ESCALATE_TO_AUTHORITIES, OTHER. Clients must tolerate future values.", "example": "NONE", "nullable": true, "type": "string" }, "publicId": { "example": "ICN-9A2C13", "pattern": "^ICN-[A-Z0-9-]+$", "type": "string" }, "reporterMessage": { "example": "We received your notice.", "nullable": true, "type": "string" }, "reviewRequestedAt": { "example": null, "format": "date-time", "nullable": true, "type": "string" }, "reviewRequestedBy": { "example": "REPORTER", "nullable": true, "type": "string" }, "status": { "description": "Current case state. Known values: SUBMITTED, IN_REVIEW, ACTION_TAKEN, NO_ACTION, ESCALATED. Clients must tolerate future values.", "example": "SUBMITTED", "type": "string" }, "targetLabel": { "example": "Evening portrait", "nullable": true, "type": "string" }, "targetType": { "description": "Resolved notice target type. Known values: GENERIC_URL, MODEL, IMAGE, VIDEO, USER_PROFILE, AVATAR, BANNER, ARTICLE, COMMENT, COLLECTION. Clients must tolerate future values.", "example": "IMAGE", "type": "string" }, "targetUrl": { "example": "https://arcenciel.io/images/108", "format": "uri", "type": "string" }, "updatedAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "publicId", "targetUrl", "targetType", "category", "status", "createdAt", "updatedAt" ], "type": "object" }, "DeveloperImageMutationResponse": { "properties": { "image": { "$ref": "#/components/schemas/Image" }, "message": { "example": "Image updated successfully", "type": "string" } }, "required": [ "message", "image" ], "type": "object" }, "DeveloperImageReactionResponse": { "properties": { "image": { "allOf": [ { "$ref": "#/components/schemas/Image" } ], "nullable": true }, "imageId": { "description": "Present when the requested reaction was already active.", "example": 108, "type": "integer" }, "message": { "example": "Reaction updated", "type": "string" } }, "required": [ "message" ], "type": "object" }, "DeveloperImageUploadResponse": { "properties": { "error": { "example": "One uploaded image was invalid; one image was accepted.", "type": "string" }, "imageIds": { "example": [ 108, 109 ], "items": { "minimum": 1, "type": "integer" }, "type": "array" }, "message": { "example": "Images uploaded successfully.", "type": "string" } }, "required": [ "imageIds" ], "type": "object" }, "DeveloperManagedImage": { "properties": { "fileName": { "example": "108.webp", "nullable": true, "type": "string" }, "filePath": { "example": "uploads/images/108.webp", "type": "string" }, "height": { "example": 1024, "nullable": true, "type": "integer" }, "id": { "example": 108, "minimum": 1, "type": "integer" }, "rating": { "example": "safe", "nullable": true, "type": "string" }, "variants": { "additionalProperties": true, "nullable": true, "type": "object" }, "width": { "example": 1024, "nullable": true, "type": "integer" } }, "required": [ "id", "filePath" ], "type": "object" }, "DeveloperMessageResponse": { "properties": { "message": { "description": "Human-readable outcome of the completed operation.", "example": "Comment deleted", "type": "string" } }, "required": [ "message" ], "type": "object" }, "DeveloperModelCreatedResponse": { "properties": { "message": { "example": "Empty model created", "type": "string" }, "modelId": { "example": 52, "minimum": 1, "type": "integer" } }, "required": [ "message", "modelId" ], "type": "object" }, "DeveloperModelMutationResponse": { "properties": { "message": { "example": "Model updated successfully", "type": "string" }, "model": { "$ref": "#/components/schemas/Model" } }, "required": [ "message", "model" ], "type": "object" }, "DeveloperModelVersionResourceCandidate": { "properties": { "baseModel": { "example": "SDXL 1.0", "nullable": true, "type": "string" }, "downloadUrl": { "example": "/api/models/52/versions/321/download", "nullable": true, "type": "string" }, "fileName": { "example": "portrait-detailer.safetensors", "nullable": true, "type": "string" }, "fileScanStatus": { "example": "CLEAN", "nullable": true, "type": "string" }, "fileSizeKb": { "example": 131072, "nullable": true, "type": "integer" }, "modelId": { "example": 52, "minimum": 1, "type": "integer" }, "modelType": { "example": "LORA", "type": "string" }, "openUrl": { "example": "/models/52#version-321", "type": "string" }, "previewImage": { "allOf": [ { "$ref": "#/components/schemas/ModelVersionResourcePreviewImage" } ], "nullable": true }, "publishAt": { "example": null, "format": "date-time", "nullable": true, "type": "string" }, "targetType": { "example": "local", "type": "string" }, "title": { "example": "Portrait Detailer", "type": "string" }, "versionId": { "example": 321, "minimum": 1, "type": "integer" }, "versionName": { "example": "v2.0", "type": "string" }, "versionStatus": { "example": "PUBLISHED", "type": "string" } }, "required": [ "targetType", "modelId", "versionId", "title", "versionName", "openUrl", "downloadUrl" ], "type": "object" }, "DeveloperModelVersionResourceCandidatesResponse": { "properties": { "candidates": { "items": { "$ref": "#/components/schemas/DeveloperModelVersionResourceCandidate" }, "type": "array" } }, "required": [ "candidates" ], "type": "object" }, "DeveloperNoticeEvidenceAttachment": { "properties": { "downloadPath": { "example": "/api/illegal-content-notices/ICN-9A2C13/attachments/ev-01HZX3", "type": "string" }, "fileName": { "example": "evidence.png", "type": "string" }, "id": { "example": "ev-01HZX3", "minLength": 1, "type": "string" }, "mimeType": { "example": "image/png", "type": "string" }, "sizeBytes": { "example": 248122, "minimum": 0, "type": "integer" }, "uploadedAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "id", "fileName", "mimeType", "sizeBytes", "uploadedAt", "downloadPath" ], "type": "object" }, "DeveloperNoticeReviewResponse": { "properties": { "message": { "example": "Review requested.", "type": "string" }, "publicId": { "example": "ICN-9A2C13", "type": "string" }, "status": { "description": "Current case state. Known values: SUBMITTED, IN_REVIEW, ACTION_TAKEN, NO_ACTION, ESCALATED. Clients must tolerate future values.", "example": "SUBMITTED", "type": "string" } }, "required": [ "message", "publicId", "status" ], "type": "object" }, "DeveloperNoticeReviewer": { "properties": { "id": { "example": 7, "minimum": 1, "type": "integer" }, "username": { "example": "moderator", "type": "string" } }, "required": [ "id", "username" ], "type": "object" }, "DeveloperNotification": { "properties": { "comment": { "allOf": [ { "$ref": "#/components/schemas/DeveloperNotificationComment" } ], "nullable": true }, "commentId": { "example": 912, "nullable": true, "type": "integer" }, "createdAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "example": 501, "type": "integer" }, "isRead": { "example": false, "type": "boolean" }, "message": { "example": "A creator commented on your model.", "type": "string" }, "type": { "description": "Forward-compatible notification type.", "example": "NEW_COMMENT", "type": "string" }, "updatedAt": { "example": "2026-08-07T10:00:00.000Z", "format": "date-time", "type": "string" }, "userId": { "example": 42, "type": "integer" } }, "required": [ "id", "userId", "type", "message", "isRead", "createdAt", "updatedAt" ], "type": "object" }, "DeveloperNotificationComment": { "properties": { "id": { "example": 912, "type": "integer" }, "targetId": { "example": 52, "type": "integer" }, "targetType": { "example": "MODEL", "type": "string" } }, "required": [ "id", "targetType", "targetId" ], "type": "object" }, "DeveloperNotificationCount": { "properties": { "total": { "example": 12, "minimum": 0, "type": "integer" }, "unread": { "example": 3, "minimum": 0, "type": "integer" } }, "required": [ "total", "unread" ], "type": "object" }, "DeveloperNotificationPage": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DeveloperNotification" }, "type": "array" }, "hasMore": { "example": false, "type": "boolean" }, "limit": { "example": 50, "maximum": 100, "minimum": 1, "type": "integer" }, "nextCursor": { "example": null, "nullable": true, "type": "string" } }, "required": [ "data", "nextCursor", "hasMore", "limit" ], "type": "object" }, "DeveloperNotificationSummary": { "properties": { "byCategory": { "additionalProperties": { "$ref": "#/components/schemas/DeveloperNotificationCount" }, "type": "object" }, "byType": { "additionalProperties": { "$ref": "#/components/schemas/DeveloperNotificationCount" }, "type": "object" }, "total": { "example": 12, "minimum": 0, "type": "integer" }, "unread": { "example": 3, "minimum": 0, "type": "integer" } }, "required": [ "total", "unread", "byType", "byCategory" ], "type": "object" }, "DeveloperPinnedTemplatesResponse": { "properties": { "message": { "example": "Pinned templates updated", "type": "string" }, "modelIds": { "example": [ 12, 18 ], "items": { "type": "integer" }, "maxItems": 3, "type": "array" }, "models": { "description": "Present only when compact=true is requested.", "items": { "$ref": "#/components/schemas/Model" }, "type": "array" } }, "required": [ "modelIds" ], "type": "object" }, "DeveloperReportResponse": { "properties": { "message": { "example": "Content reported successfully", "type": "string" } }, "required": [ "message" ], "type": "object" }, "DeveloperStoredImagesUploadResponse": { "properties": { "error": { "example": "One uploaded image was invalid; one image was accepted.", "type": "string" }, "images": { "items": { "$ref": "#/components/schemas/DeveloperManagedImage" }, "type": "array" }, "message": { "example": "Images uploaded successfully.", "type": "string" } }, "required": [ "images" ], "type": "object" }, "DeveloperStyleMatch": { "properties": { "id": { "example": 108, "minimum": 1, "type": "integer" }, "image": { "$ref": "#/components/schemas/Image" }, "layerScores": { "additionalProperties": { "type": "number" }, "type": "object" }, "score": { "example": 0.93, "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "id", "score" ], "type": "object" }, "DeveloperStyleSearchMeta": { "properties": { "availableLayers": { "example": [ "style" ], "items": { "type": "string" }, "type": "array" }, "backendKey": { "example": "clip", "nullable": true, "type": "string" }, "defaultLayers": { "example": [ "style" ], "items": { "type": "string" }, "type": "array" }, "disabled": { "example": false, "type": "boolean" }, "elapsedSeconds": { "example": 0.18, "nullable": true, "type": "number" }, "inverted": { "example": false, "type": "boolean" }, "page": { "example": 0, "minimum": 0, "type": "integer" }, "pageSize": { "example": 24, "minimum": 1, "type": "integer" }, "queriedCount": { "example": 1600, "nullable": true, "type": "integer" }, "requestedLayers": { "example": [ "style" ], "items": { "type": "string" }, "type": "array" }, "serviceHealthy": { "example": true, "type": "boolean" }, "skippedCount": { "example": 0, "nullable": true, "type": "integer" }, "sourceType": { "example": "upload", "nullable": true, "type": "string" }, "totalMatches": { "example": 1, "minimum": 0, "type": "integer" } }, "required": [ "totalMatches", "page", "pageSize", "serviceHealthy", "inverted" ], "type": "object" }, "DeveloperStyleSearchResponse": { "properties": { "error": { "example": "Style search is temporarily unavailable.", "type": "string" }, "matches": { "items": { "$ref": "#/components/schemas/DeveloperStyleMatch" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/DeveloperStyleSearchMeta" } }, "required": [ "matches", "meta" ], "type": "object" }, "DeveloperUserSummary": { "properties": { "badges": { "items": { "type": "object" }, "type": "array" }, "id": { "example": 42, "type": "integer" }, "namecardPreference": { "example": null, "nullable": true, "type": "string" }, "preferredBadge": { "nullable": true, "type": "object" }, "preferredBadgeId": { "example": null, "nullable": true, "type": "integer" }, "profilePicture": { "example": "users/42/avatar.webp", "nullable": true, "type": "string" }, "profilePictureRating": { "example": "safe", "nullable": true, "type": "string" }, "username": { "example": "rainbow-creator", "type": "string" } }, "required": [ "id", "username" ], "type": "object" }, "DeveloperVersionCreatedResponse": { "properties": { "message": { "example": "New version created", "type": "string" }, "versionId": { "example": 321, "minimum": 1, "type": "integer" } }, "required": [ "message", "versionId" ], "type": "object" }, "DeveloperVersionMutationResponse": { "properties": { "message": { "example": "Version updated successfully", "type": "string" }, "version": { "$ref": "#/components/schemas/Version" } }, "required": [ "message", "version" ], "type": "object" }, "DeveloperVideoMutationResponse": { "properties": { "message": { "example": "Video updated", "type": "string" }, "video": { "$ref": "#/components/schemas/Video" } }, "required": [ "message", "video" ], "type": "object" }, "DeveloperVideoReactionResponse": { "properties": { "message": { "example": "Reaction updated", "type": "string" }, "video": { "allOf": [ { "$ref": "#/components/schemas/Video" } ], "nullable": true }, "videoId": { "description": "Present when the requested reaction was already active.", "example": 73, "type": "integer" } }, "required": [ "message" ], "type": "object" }, "DeveloperVideoUploadResponse": { "properties": { "error": { "example": "One uploaded video was invalid; one video was accepted.", "type": "string" }, "message": { "example": "Videos uploaded", "type": "string" }, "videoIds": { "example": [ 73, 74 ], "items": { "minimum": 1, "type": "integer" }, "type": "array" } }, "required": [ "videoIds" ], "type": "object" }, "DeveloperWebhookDelivery": { "description": "Fields describing developer webhook delivery in Developer API requests and responses.", "properties": { "attemptCount": { "description": "Number of attempt records represented by this developer webhook delivery. Minimum: 0.", "minimum": 0, "type": "integer" }, "createdAt": { "description": "UTC timestamp when this developer webhook delivery was created. Format: date-time.", "format": "date-time", "type": "string" }, "endpointId": { "description": "Stable identifier for the endpoint; use it in subsequent API calls instead of a display name.", "type": "string" }, "eventId": { "description": "Stable identifier for the event; use it in subsequent API calls instead of a display name.", "example": "evt_57d188eb4444469eaf32e6707f8f13b7", "type": "string" }, "id": { "description": "Stable identifier for the developer webhook delivery; use it in subsequent API calls instead of a display name.", "example": "dly_2ed1c66c402a42489fa613a2a85e0eb0", "type": "string" }, "lastAttemptAt": { "description": "UTC timestamp for the last attempt at transition of this developer webhook delivery. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "lastError": { "description": "Last Error associated with this developer webhook delivery; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "lastStatusCode": { "description": "Numeric last status code reported for this developer webhook delivery.", "nullable": true, "type": "integer" }, "nextAttemptAt": { "description": "UTC timestamp for the next attempt at transition of this developer webhook delivery. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "responseSnippet": { "description": "Response Snippet associated with this developer webhook delivery; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "status": { "description": "Current lifecycle state of this developer webhook delivery; clients should tolerate future values. Supported values: `PENDING`, `SENDING`, `SUCCESS`, `FAILED`.", "enum": [ "PENDING", "SENDING", "SUCCESS", "FAILED" ], "type": "string" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this developer webhook delivery. Format: date-time.", "format": "date-time", "type": "string" } }, "required": [ "id", "eventId", "endpointId", "status", "attemptCount", "createdAt", "updatedAt" ], "type": "object" }, "DeveloperWebhookDeliveryResponse": { "description": "Fields describing developer webhook delivery response in Developer API requests and responses.", "properties": { "data": { "$ref": "#/components/schemas/DeveloperWebhookDelivery" } }, "required": [ "data" ], "type": "object" }, "DeveloperWebhookEndpoint": { "description": "Fields describing developer webhook endpoint in Developer API requests and responses.", "properties": { "autoDisabledAt": { "description": "UTC timestamp for the auto disabled at transition of this developer webhook endpoint. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "consecutiveFailureCount": { "description": "Number of consecutive failure records represented by this developer webhook endpoint. Minimum: 0.", "minimum": 0, "type": "integer" }, "createdAt": { "description": "UTC timestamp when this developer webhook endpoint was created. Format: date-time.", "format": "date-time", "type": "string" }, "enabled": { "description": "Whether enabled applies to this developer webhook endpoint.", "type": "boolean" }, "eventTypes": { "description": "Ordered event types entries included with this developer webhook endpoint; an empty list means none are available.", "example": [ "model.published" ], "items": { "description": "Event Types item associated with this event types; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "id": { "description": "Stable identifier for the developer webhook endpoint; use it in subsequent API calls instead of a display name.", "example": "4b2db59e-8097-45b6-8f1c-7864e570c681", "type": "string" }, "lastDeliveredAt": { "description": "UTC timestamp for the last delivered at transition of this developer webhook endpoint. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "lastError": { "description": "Last Error associated with this developer webhook endpoint; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this developer webhook endpoint; it is not a stable identifier.", "example": "Production events", "type": "string" }, "secretLastRotatedAt": { "description": "UTC timestamp for the secret last rotated at transition of this developer webhook endpoint. Format: date-time.", "format": "date-time", "type": "string" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this developer webhook endpoint. Format: date-time.", "format": "date-time", "type": "string" }, "url": { "description": "URL for the url associated with this developer webhook endpoint; do not persist temporary signed query parameters. Format: uri.", "example": "https://example.com/webhooks/arcenciel", "format": "uri", "type": "string" }, "verifiedAt": { "description": "UTC timestamp for the verified at transition of this developer webhook endpoint. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "name", "url", "enabled", "eventTypes", "consecutiveFailureCount", "createdAt", "updatedAt" ], "type": "object" }, "DeveloperWebhookEndpointResponse": { "description": "Fields describing developer webhook endpoint response in Developer API requests and responses.", "properties": { "data": { "$ref": "#/components/schemas/DeveloperWebhookEndpoint" } }, "required": [ "data" ], "type": "object" }, "DeveloperWebhookEventType": { "description": "Fields describing developer webhook event type in Developer API requests and responses.", "properties": { "description": { "description": "User-facing description of this developer webhook event type; it may contain an empty string when no description was supplied.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of developer webhook event type; clients should tolerate future values.", "example": "model.published", "type": "string" }, "version": { "description": "Version associated with this developer webhook event type; preserve server-returned values when passing them to another operation.", "example": "1", "type": "string" } }, "required": [ "type", "version", "description" ], "type": "object" }, "Emote": { "description": "Fields describing emote in Developer API requests and responses.", "properties": { "animated": { "description": "Whether animated applies to this emote.", "example": false, "type": "boolean" }, "id": { "description": "Stable identifier for the emote; use it in subsequent API calls instead of a display name.", "example": 7, "type": "integer" }, "name": { "description": "Human-readable name for this emote; it is not a stable identifier.", "example": "poggers", "type": "string" }, "url": { "description": "URL for the url associated with this emote; do not persist temporary signed query parameters.", "example": "/uploads/emotes/poggers.png", "type": "string" } }, "type": "object" }, "GeneratorAdetailerConfig": { "description": "ADetailer configuration for post-processing passes.\nAllowed detectors/orders are exposed by `GET /api/generator/options` under `limits`.\n", "properties": { "adetailerAttentionCouplePolicy": { "deprecated": true, "description": "Legacy alias for `attentionCouplePolicy`.", "type": "string" }, "adetailerDenoise": { "deprecated": true, "description": "Legacy alias for `denoise`.", "type": "number" }, "adetailerMaskMode": { "deprecated": true, "description": "Legacy alias for `maskMode`.", "type": "string" }, "adetailerTiming": { "deprecated": true, "description": "Legacy alias for `timing`.", "type": "string" }, "attentionCouplePolicy": { "default": "strict-face-bbox", "description": "Controls how ADetailer is normalized when regional prompts (`attentionCouple`) are enabled.\n`strict-face-bbox`: force/normalize face detector routing and strict regional crop clamping.\n`prefer-face`: prefer/swap to a face detector when needed, but keep user mask knobs.\n`passthrough`: keep submitted ADetailer settings unchanged.\n", "enum": [ "strict-face-bbox", "prefer-face", "passthrough" ], "type": "string" }, "confidence": { "description": "Numeric confidence reported for this generator adetailer config. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "denoise": { "default": 0.5, "description": "ADetailer denoise strength.\nIf omitted, backend defaults to `0.5`.\nFor regional prompts, strict mode applies regional-mask crop clamping\ninstead of denoise auto-capping.\n", "maximum": 1, "minimum": 0, "nullable": true, "type": "number" }, "detectionOrder": { "description": "Use one of `limits.adetailerDetectionOrders`.", "type": "string" }, "detector": { "description": "Detector associated with this generator adetailer config; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "dilate": { "default": 4, "description": "Mask dilation in pixels for the ADetailer pass.\nDuring regional prompts with strict policy this value is still honored (not force-overridden).\n", "maximum": 128, "minimum": -64, "type": "number" }, "dropSize": { "description": "Minimum bbox edge size to keep before detailing. The runtime still accepts the deprecated `drop_size` spelling, but generated clients use this canonical field.", "maximum": 4096, "minimum": 1, "type": "integer" }, "enabled": { "default": true, "description": "Whether enabled applies to this generator adetailer config.", "type": "boolean" }, "iou": { "description": "Numeric iou reported for this generator adetailer config. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "maskBlur": { "default": 4, "description": "Mask blur radius in pixels for the ADetailer pass.\nDuring regional prompts with strict policy this value is still honored (not force-overridden).\n", "maximum": 128, "minimum": 0, "type": "number" }, "maskMode": { "default": "segmentation", "description": "ADetailer mask behavior.\n`bbox-only` uses detector boxes directly (stronger edits).\n`segmentation` intersects detector boxes with segmentation masks, with automatic bbox fallback when masks are empty/tiny.\nDuring regional prompts with strict policy, backend still forwards region masks/crop clamps\nbut preserves the submitted mask mode unless you explicitly pick `bbox-only`.\n", "enum": [ "bbox-only", "segmentation" ], "type": "string" }, "maxDetections": { "default": 2, "description": "Numeric max detections reported for this generator adetailer config. Minimum: 1. Maximum: 64.", "maximum": 64, "minimum": 1, "type": "integer" }, "model": { "description": "Model associated with this generator adetailer config; preserve server-returned values when passing them to another operation.", "type": "string" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this generator adetailer config; availability depends on visibility and privacy rules.", "nullable": true, "type": "string" }, "positivePrompt": { "description": "Optional ADetailer positive prompt override.\nDuring regional prompts, split wildcards (`[SEP]`) remain supported and wildcard ordering is normalized to detector order semantics.\nBackend also accepts regional split forms `left || right`, exactly two non-empty lines (`left\\nright`),\nand `[R1] ... [R2] ...`; these are canonicalized to `left [SEP] right`.\n", "nullable": true, "type": "string" }, "timing": { "description": "For hires/upscale jobs, run ADetailer before or after upscale.\nDefault behavior: `pre-upscale` when no upscale is active, `post-upscale` when upscale is active.\n", "enum": [ "pre-upscale", "post-upscale" ], "type": "string" } }, "type": "object" }, "GeneratorCompareCost": { "description": "Fields describing generator compare cost in Developer API requests and responses.", "properties": { "budgetProfile": { "description": "Budget Profile associated with this generator compare cost; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "dailyUsage": { "description": "Number of daily generator uses charged by this compare run.", "type": "integer" }, "estimatedGpuMs": { "description": "Aggregate GPU budget estimate in milliseconds.", "type": "integer" }, "estimatedVramMb": { "description": "Aggregate VRAM budget estimate in megabytes.", "type": "integer" }, "jobs": { "description": "Number of generator jobs consumed by this compare run.", "type": "integer" }, "queueSlots": { "description": "Number of pending queue slots reserved/consumed by this compare run.", "type": "integer" }, "weight": { "description": "Aggregate generator weight used for budget and priority calculations.", "type": "number" } }, "required": [ "jobs", "queueSlots", "dailyUsage", "estimatedGpuMs", "estimatedVramMb", "weight", "budgetProfile" ], "type": "object" }, "GeneratorCompareGrid": { "description": "Fields describing generator compare grid in Developer API requests and responses.", "properties": { "downloadUrl": { "description": "URL for the download url associated with this generator compare grid; do not persist temporary signed query parameters.", "nullable": true, "type": "string" }, "height": { "description": "Numeric height reported for this generator compare grid.", "nullable": true, "type": "integer" }, "previewHeight": { "description": "Numeric preview height reported for this generator compare grid.", "nullable": true, "type": "integer" }, "previewRelativePath": { "description": "Cached WebP preview grid path used by the inline grid endpoint.", "nullable": true, "type": "string" }, "previewUpdatedAt": { "description": "UTC timestamp for the preview updated at transition of this generator compare grid.", "nullable": true, "type": "integer" }, "previewWidth": { "description": "Numeric preview width reported for this generator compare grid.", "nullable": true, "type": "integer" }, "reason": { "description": "Reason associated with this generator compare grid; preserve server-returned values when passing them to another operation.", "type": "string" }, "relativePath": { "description": "Full-resolution PNG grid path used for downloads.", "nullable": true, "type": "string" }, "status": { "description": "Current lifecycle state of this generator compare grid; clients should tolerate future values. Supported values: `pending`, `ready`, `unavailable`.", "enum": [ "pending", "ready", "unavailable" ], "type": "string" }, "updatedAt": { "description": "Latest cache timestamp for any grid artifact.", "nullable": true, "type": "integer" }, "url": { "description": "URL for the url associated with this generator compare grid; do not persist temporary signed query parameters.", "nullable": true, "type": "string" }, "width": { "description": "Numeric width reported for this generator compare grid.", "nullable": true, "type": "integer" } }, "required": [ "status", "relativePath", "previewRelativePath", "width", "height", "previewWidth", "previewHeight", "updatedAt", "previewUpdatedAt", "url", "downloadUrl" ], "type": "object" }, "GeneratorCompareResponse": { "description": "Fields describing generator compare response in Developer API requests and responses.", "properties": { "compareRun": { "$ref": "#/components/schemas/GeneratorCompareRun" }, "jobs": { "description": "Ordered jobs entries included with this generator compare response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorJobEnvelope" }, "type": "array" } }, "required": [ "compareRun", "jobs" ], "type": "object" }, "GeneratorCompareRun": { "description": "Fields describing generator compare run in Developer API requests and responses.", "properties": { "completedCount": { "description": "Number of completed records represented by this generator compare run.", "type": "integer" }, "cost": { "$ref": "#/components/schemas/GeneratorCompareCost" }, "count": { "description": "Number of count records represented by this generator compare run.", "type": "integer" }, "createdAt": { "description": "UTC timestamp when this generator compare run was created.", "nullable": true, "type": "integer" }, "failedCount": { "description": "Number of failed records represented by this generator compare run.", "type": "integer" }, "grid": { "$ref": "#/components/schemas/GeneratorCompareGrid" }, "id": { "description": "Stable identifier for the generator compare run; use it in subsequent API calls instead of a display name. Format: uuid.", "format": "uuid", "type": "string" }, "modelNames": { "description": "Ordered model names entries included with this generator compare run; an empty list means none are available.", "items": { "description": "Model Names item associated with this model names; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "pendingCount": { "description": "Number of pending records represented by this generator compare run.", "type": "integer" }, "seed": { "description": "Seed associated with this generator compare run; preserve server-returned values when passing them to another operation.", "nullable": true, "oneOf": [ { "description": "Numeric seed reported for this generator compare run.", "type": "integer" }, { "description": "Seed associated with this generator compare run; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "status": { "description": "Current lifecycle state of this generator compare run; clients should tolerate future values. Supported values: `queued`, `running`, `completed`, `failed`, `partial`.", "enum": [ "queued", "running", "completed", "failed", "partial" ], "type": "string" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this generator compare run.", "nullable": true, "type": "integer" } }, "required": [ "id", "count", "modelNames", "status", "completedCount", "failedCount", "pendingCount", "cost", "grid" ], "type": "object" }, "GeneratorError": { "description": "Fields describing generator error in Developer API requests and responses.", "properties": { "error": { "description": "Error associated with this generator error; preserve server-returned values when passing them to another operation.", "type": "string" }, "errorCode": { "description": "Stable machine-readable error code for client handling.", "type": "string" }, "safetyReason": { "description": "Present for safety-restricted output access responses (for example `nsfw`).", "nullable": true, "type": "string" }, "safetyStatus": { "description": "Present for safety-restricted output access responses.", "enum": [ "pending_review", "quarantined" ], "type": "string" } }, "required": [ "error" ], "type": "object" }, "GeneratorJob": { "additionalProperties": true, "description": "Fields describing generator job in Developer API requests and responses.", "properties": { "adetailer": { "$ref": "#/components/schemas/GeneratorAdetailerConfig" }, "attempts": { "description": "Numeric attempts reported for this generator job.", "nullable": true, "type": "integer" }, "attentionCouple": { "description": "Regional prompt payload captured for this job. Supports up to 2 regions.", "nullable": true, "properties": { "enabled": { "description": "Whether enabled applies to this attention couple.", "type": "boolean" }, "globalPromptWeight": { "default": 0.01, "description": "Numeric global prompt weight reported for this attention couple. Minimum: 0.01. Maximum: 1.", "maximum": 1, "minimum": 0.01, "type": "number" }, "regions": { "description": "Ordered regions entries included with this attention couple; an empty list means none are available.", "items": { "description": "Structured regions item details for this regions.", "properties": { "maskPath": { "description": "PNG mask path under `generator/` with alpha transparency (must include transparent + opaque alpha values).", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this regions item; availability depends on visibility and privacy rules.", "type": "string" }, "weight": { "description": "Numeric weight reported for this regions item.", "type": "number" } }, "required": [ "prompt", "maskPath", "weight" ], "type": "object" }, "maxItems": 2, "type": "array" } }, "type": "object" }, "batchSize": { "description": "Numeric batch size reported for this generator job.", "nullable": true, "type": "integer" }, "cancelled": { "description": "Whether cancelled applies to this generator job.", "nullable": true, "type": "boolean" }, "cfg": { "description": "Numeric cfg reported for this generator job.", "nullable": true, "type": "number" }, "comfy": { "description": "Structured comfy details for this generator job.", "nullable": true, "properties": { "messages": { "description": "Ordered messages entries included with this comfy; an empty list means none are available.", "items": { "additionalProperties": true, "description": "Structured messages item details for this messages.", "type": "object" }, "type": "array" }, "nodeErrors": { "description": "Ordered node errors entries included with this comfy; an empty list means none are available.", "items": { "additionalProperties": true, "description": "Structured node errors item details for this node errors.", "type": "object" }, "type": "array" }, "status": { "description": "Current lifecycle state of this comfy; clients should tolerate future values.", "nullable": true, "type": "string" } }, "type": "object" }, "controlnets": { "description": "Ordered controlnets entries included with this generator job; an empty list means none are available.", "items": { "description": "Structured controlnets item details for this controlnets.", "properties": { "end": { "description": "Numeric end reported for this controlnets item.", "nullable": true, "type": "number" }, "imagePath": { "description": "Server-provided path for the image path associated with this controlnets item; treat it as opaque.", "type": "string" }, "model": { "description": "Model associated with this controlnets item; preserve server-returned values when passing them to another operation.", "type": "string" }, "start": { "description": "Numeric start reported for this controlnets item.", "nullable": true, "type": "number" }, "strength": { "description": "Numeric strength reported for this controlnets item.", "nullable": true, "type": "number" } }, "required": [ "model", "imagePath" ], "type": "object" }, "nullable": true, "type": "array" }, "createdAt": { "description": "Unix epoch timestamp in milliseconds.", "type": "integer" }, "deletedAt": { "description": "Unix epoch timestamp in milliseconds.", "nullable": true, "type": "integer" }, "deletedByUserId": { "description": "Stable identifier for the deleted by user; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "denoise": { "description": "Numeric denoise reported for this generator job.", "nullable": true, "type": "number" }, "diagnostics": { "description": "Structured diagnostics details for this generator job.", "nullable": true, "properties": { "adetailer": { "additionalProperties": true, "description": "Structured adetailer details for this diagnostics.", "nullable": true, "type": "object" }, "adetailerBridge": { "description": "Structured adetailer bridge details for this diagnostics.", "nullable": true, "properties": { "failed": { "description": "Whether failed applies to this adetailer bridge.", "type": "boolean" }, "reason": { "description": "Reason associated with this adetailer bridge; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "updatedAt": { "description": "Unix epoch timestamp in milliseconds.", "nullable": true, "type": "integer" } }, "type": "object" }, "attentionCouple": { "additionalProperties": true, "description": "Structured attention couple details for this diagnostics.", "nullable": true, "type": "object" }, "historyTimeoutMs": { "description": "Numeric history timeout ms reported for this diagnostics.", "nullable": true, "type": "integer" }, "workflowCaptured": { "description": "Whether workflow captured applies to this diagnostics.", "type": "boolean" } }, "type": "object" }, "error": { "description": "Error associated with this generator job; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "expiresAt": { "description": "Unix epoch timestamp in milliseconds.", "nullable": true, "type": "integer" }, "extraSeed": { "description": "A1111-like secondary seed (subseed equivalent) used for noise variation.", "nullable": true, "oneOf": [ { "description": "Numeric extra seed reported for this generator job.", "type": "integer" }, { "description": "Extra Seed associated with this generator job; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "extraSeedStrength": { "description": "Numeric extra seed strength reported for this generator job. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number" }, "height": { "description": "Numeric height reported for this generator job.", "nullable": true, "type": "integer" }, "id": { "description": "Stable identifier for the generator job; use it in subsequent API calls instead of a display name.", "type": "string" }, "imagePath": { "description": "Server-provided path for the image path associated with this generator job; treat it as opaque.", "nullable": true, "type": "string" }, "loraName": { "description": "Human-readable lora name for this generator job; it is not a stable identifier.", "nullable": true, "type": "string" }, "loras": { "description": "Ordered loras entries included with this generator job; an empty list means none are available.", "items": { "description": "Structured loras item details for this loras.", "properties": { "name": { "description": "Human-readable name for this loras item; it is not a stable identifier.", "type": "string" }, "weight": { "description": "Numeric weight reported for this loras item.", "nullable": true, "type": "number" } }, "required": [ "name" ], "type": "object" }, "nullable": true, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Structured metadata details for this generator job.", "nullable": true, "type": "object" }, "mode": { "description": "Mode associated with this generator job; preserve server-returned values when passing them to another operation. Supported values: `txt2img`, `img2img`, `inpaint`.", "enum": [ "txt2img", "img2img", "inpaint" ], "type": "string" }, "modelCapabilities": { "description": "Ordered model capabilities entries included with this generator job; an empty list means none are available.", "items": { "description": "Model Capabilities item associated with this model capabilities; preserve server-returned values when passing them to another operation.", "type": "string" }, "nullable": true, "type": "array" }, "modelName": { "description": "Human-readable model name for this generator job; it is not a stable identifier.", "nullable": true, "type": "string" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this generator job; availability depends on visibility and privacy rules.", "nullable": true, "type": "string" }, "outputToken": { "description": "Short-lived token for direct output access.", "nullable": true, "type": "string" }, "outputs": { "description": "Ordered outputs entries included with this generator job; an empty list means none are available.", "items": { "description": "Structured outputs item details for this outputs.", "properties": { "filename": { "description": "Client-visible filename for this outputs item; do not use it as a resource identifier or filesystem path without sanitizing it.", "type": "string" }, "subfolder": { "description": "Subfolder associated with this outputs item; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of outputs item; clients should tolerate future values.", "nullable": true, "type": "string" } }, "required": [ "filename", "subfolder" ], "type": "object" }, "nullable": true, "type": "array" }, "outputsExpiredAt": { "description": "Unix epoch timestamp in milliseconds.", "nullable": true, "type": "integer" }, "position": { "description": "Queue position hint, present on list/SSE payloads.", "nullable": true, "type": "integer" }, "priority": { "description": "Numeric priority reported for this generator job.", "nullable": true, "type": "integer" }, "progress": { "$ref": "#/components/schemas/GeneratorJobProgress" }, "prompt": { "description": "Prompt text associated with generation of this generator job; availability depends on visibility and privacy rules.", "type": "string" }, "promptControl": { "description": "Prompt Control state used for this job.", "nullable": true, "properties": { "enabled": { "description": "Whether enabled applies to this prompt control.", "type": "boolean" }, "mode": { "description": "Mode associated with this prompt control; preserve server-returned values when passing them to another operation. Supported values: `manual`, `auto`, `disabled`.", "enum": [ "manual", "auto", "disabled" ], "type": "string" }, "source": { "description": "Source associated with this prompt control; preserve server-returned values when passing them to another operation. Supported values: `explicit`, `auto`.", "enum": [ "explicit", "auto" ], "type": "string" } }, "type": "object" }, "publishedOutputs": { "description": "Ordered published outputs entries included with this generator job; an empty list means none are available.", "items": { "description": "Published Outputs item associated with this published outputs; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "queueEtaMs": { "description": "Estimated queue wait time in milliseconds for this job hint.", "nullable": true, "type": "integer" }, "rfShift": { "description": "Numeric rf shift reported for this generator job.", "nullable": true, "type": "number" }, "role": { "description": "Access role represented by this generator job; use it for display and capability checks, not authentication.", "type": "string" }, "safety": { "$ref": "#/components/schemas/GeneratorSafetySnapshot" }, "samplerName": { "description": "Human-readable sampler name for this generator job; it is not a stable identifier.", "nullable": true, "type": "string" }, "scaleFactor": { "description": "Numeric scale factor reported for this generator job.", "nullable": true, "type": "number" }, "scheduler": { "description": "Scheduler associated with this generator job; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "seed": { "description": "Seed associated with this generator job; preserve server-returned values when passing them to another operation.", "nullable": true, "oneOf": [ { "description": "Numeric seed reported for this generator job.", "type": "integer" }, { "description": "Seed associated with this generator job; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "status": { "description": "Current lifecycle state of this generator job; clients should tolerate future values. Supported values: `queued`, `running`, `completed`, `failed`.", "enum": [ "queued", "running", "completed", "failed" ], "type": "string" }, "steps": { "description": "Numeric steps reported for this generator job.", "nullable": true, "type": "integer" }, "storage": { "$ref": "#/components/schemas/GeneratorStorageStatus" }, "taggerTags": { "description": "Ordered tagger tags entries included with this generator job; an empty list means none are available.", "items": { "description": "Tagger Tags item associated with this tagger tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "tags": { "description": "Ordered tags entries included with this generator job; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "updatedAt": { "description": "Unix epoch timestamp in milliseconds.", "type": "integer" }, "upscaleModelName": { "description": "Human-readable upscale model name for this generator job; it is not a stable identifier.", "nullable": true, "type": "string" }, "upscaleProfiles": { "description": "Ordered upscale profiles entries included with this generator job; an empty list means none are available.", "items": { "description": "Structured upscale profiles item details for this upscale profiles.", "properties": { "denoise": { "description": "Numeric denoise reported for this upscale profiles item.", "nullable": true, "type": "number" }, "modelName": { "description": "Human-readable model name for this upscale profiles item; it is not a stable identifier.", "type": "string" } }, "required": [ "modelName" ], "type": "object" }, "nullable": true, "type": "array" }, "upscaleTargetHeight": { "description": "Numeric upscale target height reported for this generator job.", "nullable": true, "type": "integer" }, "upscaleTargetWidth": { "description": "Numeric upscale target width reported for this generator job.", "nullable": true, "type": "integer" }, "userId": { "description": "Stable identifier for the user; use it in subsequent API calls instead of a display name.", "type": "integer" }, "vaeName": { "description": "Human-readable vae name for this generator job; it is not a stable identifier.", "nullable": true, "type": "string" }, "weight": { "description": "Numeric weight reported for this generator job.", "nullable": true, "type": "number" }, "width": { "description": "Numeric width reported for this generator job.", "nullable": true, "type": "integer" } }, "required": [ "id", "userId", "mode", "prompt", "status", "createdAt", "updatedAt" ], "type": "object" }, "GeneratorJobEnvelope": { "description": "Fields describing generator job envelope in Developer API requests and responses.", "properties": { "job": { "$ref": "#/components/schemas/GeneratorJob" }, "position": { "description": "Numeric position reported for this generator job envelope.", "nullable": true, "type": "integer" }, "queueEtaMs": { "description": "Numeric queue eta ms reported for this generator job envelope.", "nullable": true, "type": "integer" } }, "required": [ "job", "position", "queueEtaMs" ], "type": "object" }, "GeneratorJobListItem": { "allOf": [ { "$ref": "#/components/schemas/GeneratorJob" }, { "description": "Fields describing generator job list item in Developer API requests and responses.", "properties": { "position": { "description": "Queue position hint.", "nullable": true, "type": "integer" }, "queueEtaMs": { "description": "Estimated queue wait time in milliseconds.", "nullable": true, "type": "integer" } }, "type": "object" } ], "description": "Generator Job List Item value documented for this operation." }, "GeneratorJobListResponse": { "description": "Fields describing generator job list response in Developer API requests and responses.", "properties": { "jobs": { "description": "Ordered jobs entries included with this generator job list response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorJobListItem" }, "type": "array" }, "nextCursor": { "description": "Opaque continuation token for the next page of this generator job list response; absent or null means iteration is complete.", "nullable": true, "type": "string" } }, "required": [ "jobs", "nextCursor" ], "type": "object" }, "GeneratorJobProgress": { "description": "Fields describing generator job progress in Developer API requests and responses.", "properties": { "detail": { "description": "Structured detail details for this generator job progress.", "nullable": true, "properties": { "elapsedMs": { "description": "Numeric elapsed ms reported for this detail.", "nullable": true, "type": "integer" }, "max": { "description": "Numeric max reported for this detail.", "nullable": true, "type": "number" }, "nodeId": { "description": "Stable identifier for the node; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "string" }, "ratio": { "description": "Numeric ratio reported for this detail. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "nullable": true, "type": "number" }, "source": { "description": "Source associated with this detail; preserve server-returned values when passing them to another operation. Supported values: `comfy_progress`, `comfy_progress_state`, `history_poll`, `finalizing`.", "enum": [ "comfy_progress", "comfy_progress_state", "history_poll", "finalizing" ], "type": "string" }, "timeoutMs": { "description": "Numeric timeout ms reported for this detail.", "nullable": true, "type": "integer" }, "value": { "description": "Numeric value reported for this detail.", "nullable": true, "type": "number" } }, "type": "object" }, "etaMs": { "description": "Numeric eta ms reported for this generator job progress.", "nullable": true, "type": "integer" }, "percent": { "description": "Numeric percent reported for this generator job progress.", "type": "number" }, "phase": { "description": "Phase associated with this generator job progress; preserve server-returned values when passing them to another operation. Supported values: `queued`, `warmup`, `generating`, `refining`, `upscaling`, `finalizing`, `completed`, `failed`.", "enum": [ "queued", "warmup", "generating", "refining", "upscaling", "finalizing", "completed", "failed" ], "type": "string" }, "updatedAt": { "description": "Unix epoch timestamp in milliseconds.", "type": "integer" } }, "required": [ "phase", "percent", "updatedAt" ], "type": "object" }, "GeneratorJobRemixRequest": { "additionalProperties": false, "description": "Same override fields as `POST /api/generator/jobs`.", "properties": { "adetailer": { "$ref": "#/components/schemas/GeneratorAdetailerConfig" }, "adetailerDetectionOrder": { "deprecated": true, "description": "Adetailer Detection Order associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "type": "string" }, "adetailerNegative": { "deprecated": true, "description": "Adetailer Negative associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "type": "string" }, "adetailerPositive": { "deprecated": true, "description": "Adetailer Positive associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "type": "string" }, "attentionCouple": { "description": "Regional prompt payload. Supports up to 2 regions.\nAccepted prompt split forms include `left || right` and exactly two non-empty lines.\n", "properties": { "enabled": { "description": "Whether enabled applies to this attention couple.", "type": "boolean" }, "globalPromptWeight": { "default": 0.01, "description": "Optional compatibility/base blend weight.", "maximum": 1, "minimum": 0.01, "type": "number" }, "regions": { "description": "Ordered regions entries included with this attention couple; an empty list means none are available.", "items": { "description": "Structured regions item details for this regions.", "properties": { "maskPath": { "description": "PNG mask path under `generator/` with alpha transparency (must include transparent + opaque alpha values).", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this regions item; availability depends on visibility and privacy rules.", "type": "string" }, "weight": { "description": "Numeric weight reported for this regions item. Minimum: 0.01. Maximum: 1.", "maximum": 1, "minimum": 0.01, "type": "number" } }, "required": [ "prompt", "maskPath" ], "type": "object" }, "maxItems": 2, "type": "array" } }, "type": "object" }, "batchSize": { "description": "`txt2img` only.\nMust be `1` when upscale/hires is enabled.\n", "type": "integer" }, "cfg": { "description": "Numeric cfg reported for this generator job remix request.", "type": "number" }, "controlnets": { "description": "Ordered controlnets entries included with this generator job remix request; an empty list means none are available.", "items": { "description": "Structured controlnets item details for this controlnets.", "properties": { "end": { "description": "Numeric end reported for this controlnets item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "imagePath": { "description": "Server-provided path for the image path associated with this controlnets item; treat it as opaque.", "type": "string" }, "model": { "description": "Model associated with this controlnets item; preserve server-returned values when passing them to another operation.", "type": "string" }, "modelName": { "description": "Human-readable model name for this controlnets item; it is not a stable identifier.", "type": "string" }, "start": { "description": "Numeric start reported for this controlnets item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "strength": { "description": "Numeric strength reported for this controlnets item. Minimum: 0. Maximum: 2.", "maximum": 2, "minimum": 0, "type": "number" } }, "type": "object" }, "type": "array" }, "denoise": { "description": "Numeric denoise reported for this generator job remix request.", "type": "number" }, "extraSeed": { "description": "Extra Seed associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "oneOf": [ { "description": "Numeric extra seed reported for this generator job remix request.", "type": "integer" }, { "description": "Extra Seed associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "extraSeedStrength": { "description": "Numeric extra seed strength reported for this generator job remix request. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "height": { "description": "Numeric height reported for this generator job remix request.", "type": "integer" }, "imagePath": { "description": "Server-provided path for the image path associated with this generator job remix request; treat it as opaque.", "type": "string" }, "loraName": { "description": "Human-readable lora name for this generator job remix request; it is not a stable identifier.", "type": "string" }, "loras": { "description": "Ordered loras entries included with this generator job remix request; an empty list means none are available.", "items": { "description": "Loras item associated with this loras; preserve server-returned values when passing them to another operation.", "oneOf": [ { "description": "Loras item associated with this loras; preserve server-returned values when passing them to another operation.", "type": "string" }, { "description": "Structured loras item details for this loras.", "properties": { "name": { "description": "Human-readable name for this loras item; it is not a stable identifier.", "type": "string" }, "weight": { "description": "Numeric weight reported for this loras item.", "type": "number" } }, "type": "object" } ] }, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Structured metadata details for this generator job remix request.", "nullable": true, "type": "object" }, "mode": { "description": "Mode associated with this generator job remix request; preserve server-returned values when passing them to another operation. Supported values: `txt2img`, `img2img`, `inpaint`.", "enum": [ "txt2img", "img2img", "inpaint" ], "type": "string" }, "modelName": { "description": "Human-readable model name for this generator job remix request; it is not a stable identifier.", "type": "string" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this generator job remix request; availability depends on visibility and privacy rules.", "type": "string" }, "presetId": { "description": "Stable identifier for the preset; use it in subsequent API calls instead of a display name.", "type": "integer" }, "prompt": { "description": "Prompt text associated with generation of this generator job remix request; availability depends on visibility and privacy rules.", "type": "string" }, "promptControl": { "description": "Enables Prompt Control for schedule syntax, or `auto` to enable only when schedule syntax is present.", "oneOf": [ { "description": "Whether prompt control applies to this generator job remix request.", "type": "boolean" }, { "description": "Prompt Control associated with this generator job remix request; preserve server-returned values when passing them to another operation. Supported values: `auto`, `true`, `false`.", "enum": [ "auto", true, false ], "type": "string" }, { "description": "Structured prompt control details for this generator job remix request.", "properties": { "enabled": { "description": "Whether enabled applies to this prompt control.", "type": "boolean" }, "mode": { "description": "Mode associated with this prompt control; preserve server-returned values when passing them to another operation. Supported values: `auto`, `manual`, `disabled`.", "enum": [ "auto", "manual", "disabled" ], "type": "string" } }, "type": "object" } ] }, "retentionDays": { "description": "Numeric retention days reported for this generator job remix request.", "type": "integer" }, "rfShift": { "description": "Numeric rf shift reported for this generator job remix request. Minimum: 1. Maximum: 15.", "maximum": 15, "minimum": 1, "type": "number" }, "samplerName": { "description": "Human-readable sampler name for this generator job remix request; it is not a stable identifier.", "type": "string" }, "scaleFactor": { "description": "Upscale factor target. Applied only when `upscaleProfiles` (or legacy `upscaleModelName`) is set; otherwise treated as `1`.", "type": "number" }, "scheduler": { "description": "Scheduler associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "type": "string" }, "schedulerName": { "deprecated": true, "description": "Human-readable scheduler name for this generator job remix request; it is not a stable identifier.", "type": "string" }, "seed": { "description": "Seed associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "oneOf": [ { "description": "Numeric seed reported for this generator job remix request.", "type": "integer" }, { "description": "Seed associated with this generator job remix request; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "sfwMode": { "description": "Whether sfw mode applies to this generator job remix request.", "type": "boolean" }, "steps": { "description": "Numeric steps reported for this generator job remix request.", "type": "integer" }, "tags": { "description": "Ordered tags entries included with this generator job remix request; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "upscaleProfiles": { "description": "Ordered upscale profiles entries included with this generator job remix request; an empty list means none are available.", "items": { "description": "Structured upscale profiles item details for this upscale profiles.", "properties": { "denoise": { "description": "Denoise strength for the upscale refinement pass. x4 upscalers with denoise > 0 require a target `scaleFactor`.", "maximum": 1, "minimum": 0, "type": "number" }, "model": { "description": "Model associated with this upscale profiles item; preserve server-returned values when passing them to another operation.", "type": "string" }, "modelName": { "description": "Human-readable model name for this upscale profiles item; it is not a stable identifier.", "type": "string" }, "upscaleModelName": { "description": "Human-readable upscale model name for this upscale profiles item; it is not a stable identifier.", "type": "string" } }, "type": "object" }, "type": "array" }, "vaeName": { "description": "Human-readable vae name for this generator job remix request; it is not a stable identifier.", "type": "string" }, "width": { "description": "Numeric width reported for this generator job remix request.", "type": "integer" } }, "required": [ "prompt" ], "type": "object" }, "GeneratorModelCatalog": { "description": "Fields describing generator model catalog in Developer API requests and responses.", "properties": { "adetailer": { "description": "Ordered adetailer entries included with this generator model catalog; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorModelCatalogEntry" }, "type": "array" }, "checkpoints": { "description": "Ordered checkpoints entries included with this generator model catalog; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorModelCatalogEntry" }, "type": "array" }, "loras": { "description": "Ordered loras entries included with this generator model catalog; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorModelCatalogEntry" }, "type": "array" } }, "required": [ "checkpoints", "loras", "adetailer" ], "type": "object" }, "GeneratorModelCatalogEntry": { "description": "Fields describing generator model catalog entry in Developer API requests and responses.", "properties": { "baseModel": { "description": "Base Model associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "coverImage": { "description": "Cover Image associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "coverRating": { "description": "Cover Rating associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "favoriteCount": { "description": "Number of favorite records represented by this generator model catalog entry.", "nullable": true, "type": "integer" }, "modelCapabilities": { "description": "Ordered model capabilities entries included with this generator model catalog entry; an empty list means none are available.", "items": { "description": "Model Capabilities item associated with this model capabilities; preserve server-returned values when passing them to another operation.", "type": "string" }, "nullable": true, "type": "array" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "modelTags": { "description": "Ordered model tags entries included with this generator model catalog entry; an empty list means none are available.", "items": { "description": "Model Tags item associated with this model tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "nullable": true, "type": "array" }, "modelTitle": { "description": "Human-readable title/label for UI display (`displayName` equivalent for catalog responses).", "type": "string" }, "modelType": { "description": "Discriminator identifying the kind of generator model catalog entry; clients should tolerate future values.", "nullable": true, "type": "string" }, "modelVersionCount": { "description": "Number of model version records represented by this generator model catalog entry.", "nullable": true, "type": "integer" }, "modelVersionRank": { "description": "Position of this version within the model order (0 = first/latest).", "nullable": true, "type": "integer" }, "name": { "description": "Human-readable name for this generator model catalog entry; it is not a stable identifier.", "type": "string" }, "precision": { "description": "Precision associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "previewImage": { "description": "Preview Image associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "previewRating": { "description": "Preview Rating associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "rfRequiredNotes": { "description": "Ordered rf required notes entries included with this generator model catalog entry; an empty list means none are available.", "items": { "description": "Rf Required Notes item associated with this rf required notes; preserve server-returned values when passing them to another operation.", "type": "string" }, "nullable": true, "type": "array" }, "triggerPrompts": { "description": "Ordered trigger prompts entries included with this generator model catalog entry; an empty list means none are available.", "items": { "description": "Trigger Prompts item associated with this trigger prompts; preserve server-returned values when passing them to another operation.", "type": "string" }, "nullable": true, "type": "array" }, "uploaderId": { "description": "Stable identifier for the uploader; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "uploaderProfilePicture": { "description": "Uploader Profile Picture associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "uploaderUsername": { "description": "Uploader Username associated with this generator model catalog entry; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "versionId": { "description": "Stable identifier for the version; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "versionName": { "description": "Human-readable version name for this generator model catalog entry; it is not a stable identifier.", "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "GeneratorOptionsResponse": { "description": "Fields describing generator options response in Developer API requests and responses.", "properties": { "limits": { "description": "Structured limits details for this generator options response.", "properties": { "adetailerAttentionCouplePolicies": { "description": "Ordered adetailer attention couple policies entries included with this limits; an empty list means none are available.", "items": { "description": "Adetailer Attention Couple Policies item associated with this adetailer attention couple policies; preserve server-returned values when passing them to another operation. Supported values: `strict-face-bbox`, `prefer-face`, `passthrough`.", "enum": [ "strict-face-bbox", "prefer-face", "passthrough" ], "type": "string" }, "type": "array" }, "adetailerAttentionCouplePolicyDefault": { "description": "Adetailer Attention Couple Policy Default associated with this limits; preserve server-returned values when passing them to another operation. Supported values: `strict-face-bbox`, `prefer-face`, `passthrough`.", "enum": [ "strict-face-bbox", "prefer-face", "passthrough" ], "type": "string" }, "adetailerDetectionOrderDefault": { "description": "Adetailer Detection Order Default associated with this limits; preserve server-returned values when passing them to another operation.", "type": "string" }, "adetailerDetectionOrders": { "description": "Ordered adetailer detection orders entries included with this limits; an empty list means none are available.", "items": { "description": "Adetailer Detection Orders item associated with this adetailer detection orders; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "adetailerDetectors": { "description": "Ordered adetailer detectors entries included with this limits; an empty list means none are available.", "items": { "description": "Adetailer Detectors item associated with this adetailer detectors; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "adetailerEnabled": { "description": "Whether adetailer enabled applies to this limits.", "type": "boolean" }, "adetailerMaskModeDefault": { "description": "Adetailer Mask Mode Default associated with this limits; preserve server-returned values when passing them to another operation. Supported values: `bbox-only`, `segmentation`.", "enum": [ "bbox-only", "segmentation" ], "type": "string" }, "adetailerMaskModes": { "description": "Ordered adetailer mask modes entries included with this limits; an empty list means none are available.", "items": { "description": "Adetailer Mask Modes item associated with this adetailer mask modes; preserve server-returned values when passing them to another operation. Supported values: `bbox-only`, `segmentation`.", "enum": [ "bbox-only", "segmentation" ], "type": "string" }, "type": "array" }, "adetailerModels": { "description": "Ordered adetailer models entries included with this limits; an empty list means none are available.", "items": { "description": "Adetailer Models item associated with this adetailer models; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "compareEnabled": { "description": "Whether compare enabled applies to this limits.", "type": "boolean" }, "maxBatchSize": { "description": "Numeric max batch size reported for this limits.", "type": "integer" }, "maxCfg": { "description": "Numeric max cfg reported for this limits.", "type": "number" }, "maxCompareTargets": { "description": "Numeric max compare targets reported for this limits.", "type": "integer" }, "maxPixels": { "description": "Numeric max pixels reported for this limits.", "type": "integer" }, "maxResolution": { "description": "Numeric max resolution reported for this limits.", "type": "integer" }, "maxScaleFactor": { "description": "Numeric max scale factor reported for this limits.", "type": "number" }, "maxSteps": { "description": "Numeric max steps reported for this limits.", "type": "integer" }, "maxUpscaleProfiles": { "description": "Numeric max upscale profiles reported for this limits.", "type": "integer" }, "maxWeight": { "description": "Numeric max weight reported for this limits.", "type": "number" }, "samplers": { "description": "Ordered samplers entries included with this limits; an empty list means none are available.", "items": { "description": "Samplers item associated with this samplers; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "schedulers": { "description": "Ordered schedulers entries included with this limits; an empty list means none are available.", "items": { "description": "Schedulers item associated with this schedulers; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" } }, "required": [ "maxSteps", "maxCfg", "maxResolution", "maxPixels", "maxScaleFactor", "maxBatchSize", "maxCompareTargets", "compareEnabled", "maxUpscaleProfiles", "maxWeight", "samplers", "schedulers", "adetailerEnabled", "adetailerModels", "adetailerDetectors", "adetailerDetectionOrders", "adetailerDetectionOrderDefault", "adetailerMaskModes", "adetailerMaskModeDefault", "adetailerAttentionCouplePolicies", "adetailerAttentionCouplePolicyDefault" ], "type": "object" }, "modelCapabilities": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "Structured model capabilities details for this generator options response.", "type": "object" }, "modelDetails": { "description": "Structured model details details for this generator options response.", "properties": { "adetailer": { "description": "Ordered adetailer entries included with this model details; an empty list means none are available.", "items": { "description": "Structured adetailer item details for this adetailer.", "properties": { "baseModel": { "description": "Base Model associated with this adetailer item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "displayName": { "description": "Human-readable display name for this adetailer item; it is not a stable identifier.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this adetailer item; it is not a stable identifier.", "type": "string" }, "precision": { "description": "Precision associated with this adetailer item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" }, "checkpoints": { "description": "Ordered checkpoints entries included with this model details; an empty list means none are available.", "items": { "description": "Structured checkpoints item details for this checkpoints.", "properties": { "baseModel": { "description": "Base Model associated with this checkpoints item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "displayName": { "description": "Human-readable display name for this checkpoints item; it is not a stable identifier.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this checkpoints item; it is not a stable identifier.", "type": "string" }, "precision": { "description": "Precision associated with this checkpoints item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" }, "controlnets": { "description": "Ordered controlnets entries included with this model details; an empty list means none are available.", "items": { "description": "Structured controlnets item details for this controlnets.", "properties": { "baseModel": { "description": "Base Model associated with this controlnets item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "displayName": { "description": "Human-readable display name for this controlnets item; it is not a stable identifier.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this controlnets item; it is not a stable identifier.", "type": "string" }, "precision": { "description": "Precision associated with this controlnets item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" }, "loras": { "description": "Ordered loras entries included with this model details; an empty list means none are available.", "items": { "description": "Structured loras item details for this loras.", "properties": { "baseModel": { "description": "Base Model associated with this loras item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "displayName": { "description": "Human-readable display name for this loras item; it is not a stable identifier.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this loras item; it is not a stable identifier.", "type": "string" }, "precision": { "description": "Precision associated with this loras item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" }, "upscale": { "description": "Ordered upscale entries included with this model details; an empty list means none are available.", "items": { "description": "Structured upscale item details for this upscale.", "properties": { "baseModel": { "description": "Base Model associated with this upscale item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "displayName": { "description": "Human-readable display name for this upscale item; it is not a stable identifier.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this upscale item; it is not a stable identifier.", "type": "string" }, "precision": { "description": "Precision associated with this upscale item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" }, "vae": { "description": "Ordered vae entries included with this model details; an empty list means none are available.", "items": { "description": "Structured vae item details for this vae.", "properties": { "baseModel": { "description": "Base Model associated with this vae item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "displayName": { "description": "Human-readable display name for this vae item; it is not a stable identifier.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this vae item; it is not a stable identifier.", "type": "string" }, "precision": { "description": "Precision associated with this vae item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "required": [ "checkpoints", "loras", "upscale", "controlnets", "adetailer", "vae" ], "type": "object" }, "models": { "description": "Structured models details for this generator options response.", "properties": { "adetailer": { "description": "Ordered adetailer entries included with this models; an empty list means none are available.", "items": { "description": "Adetailer item associated with this adetailer; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "checkpoints": { "description": "Ordered checkpoints entries included with this models; an empty list means none are available.", "items": { "description": "Checkpoints item associated with this checkpoints; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "controlnets": { "description": "Ordered controlnets entries included with this models; an empty list means none are available.", "items": { "description": "Controlnets item associated with this controlnets; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "loras": { "description": "Ordered loras entries included with this models; an empty list means none are available.", "items": { "description": "Loras item associated with this loras; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "upscale": { "description": "Ordered upscale entries included with this models; an empty list means none are available.", "items": { "description": "Upscale item associated with this upscale; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "vae": { "description": "Ordered vae entries included with this models; an empty list means none are available.", "items": { "description": "Vae item associated with this vae; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" } }, "required": [ "checkpoints", "loras", "upscale", "controlnets", "adetailer", "vae" ], "type": "object" }, "quota": { "$ref": "#/components/schemas/GeneratorQuotaSnapshot" }, "rfRequiredNotes": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "Structured rf required notes details for this generator options response.", "type": "object" }, "settings": { "description": "Structured settings details for this generator options response.", "properties": { "defaults": { "additionalProperties": true, "description": "Structured defaults details for this settings.", "type": "object" }, "retentionOptions": { "description": "Ordered retention options entries included with this settings; an empty list means none are available.", "items": { "description": "Numeric retention options item reported for this retention options.", "type": "integer" }, "type": "array" } }, "required": [ "defaults", "retentionOptions" ], "type": "object" } }, "required": [ "models", "modelDetails", "modelCapabilities", "rfRequiredNotes", "settings", "limits", "quota" ], "type": "object" }, "GeneratorPreset": { "description": "Fields describing generator preset in Developer API requests and responses.", "properties": { "createdAt": { "description": "UTC timestamp when this generator preset was created. Format: date-time.", "format": "date-time", "type": "string" }, "description": { "description": "User-facing description of this generator preset; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "id": { "description": "Stable identifier for the generator preset; use it in subsequent API calls instead of a display name.", "type": "integer" }, "isPublic": { "description": "Whether is public applies to this generator preset.", "type": "boolean" }, "name": { "description": "Human-readable name for this generator preset; it is not a stable identifier.", "type": "string" }, "ownerId": { "description": "Stable identifier for the owner; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "payload": { "additionalProperties": true, "description": "Structured payload details for this generator preset.", "type": "object" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this generator preset. Format: date-time.", "format": "date-time", "type": "string" } }, "required": [ "id", "name", "payload", "isPublic" ], "type": "object" }, "GeneratorPresetExport": { "description": "Fields describing generator preset export in Developer API requests and responses.", "properties": { "exportedAt": { "description": "UTC timestamp for the exported at transition of this generator preset export. Format: date-time.", "format": "date-time", "type": "string" }, "preset": { "description": "Structured preset details for this generator preset export.", "properties": { "description": { "description": "User-facing description of this preset; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this preset; it is not a stable identifier.", "type": "string" }, "payload": { "additionalProperties": true, "description": "Structured payload details for this preset.", "type": "object" } }, "required": [ "name", "payload" ], "type": "object" }, "version": { "description": "Numeric version reported for this generator preset export.", "type": "integer" } }, "required": [ "version", "exportedAt", "preset" ], "type": "object" }, "GeneratorPublishResponse": { "description": "Fields describing generator publish response in Developer API requests and responses.", "properties": { "alreadyPublished": { "description": "Ordered already published entries included with this generator publish response; an empty list means none are available.", "items": { "description": "Already Published item associated with this already published; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "alreadyPublishedCount": { "description": "Number of already published records represented by this generator publish response.", "type": "integer" }, "count": { "description": "Number of count records represented by this generator publish response.", "type": "integer" }, "images": { "description": "Ordered images entries included with this generator publish response; an empty list means none are available.", "items": { "additionalProperties": true, "description": "Structured images item details for this images.", "type": "object" }, "type": "array" } }, "required": [ "images", "count", "alreadyPublished", "alreadyPublishedCount" ], "type": "object" }, "GeneratorQuotaBudgetBucket": { "description": "Structured gpu ms details for this budgets.", "properties": { "limit": { "description": "Maximum number of records requested or returned in one page of this gpu ms.", "type": "integer" }, "remaining": { "description": "Numeric remaining reported for this gpu ms.", "nullable": true, "type": "integer" }, "used": { "description": "Numeric used reported for this gpu ms.", "type": "integer" } }, "required": [ "limit", "used", "remaining" ], "type": "object" }, "GeneratorQuotaBudgets": { "description": "Structured budgets details for this quota.", "properties": { "gpuMs": { "$ref": "#/components/schemas/GeneratorQuotaBudgetBucket" }, "profile": { "description": "Profile associated with this budgets; preserve server-returned values when passing them to another operation.", "type": "string" }, "vramMb": { "$ref": "#/components/schemas/GeneratorQuotaBudgetBucket" } }, "required": [ "profile", "gpuMs", "vramMb" ], "type": "object" }, "GeneratorQuotaCounter": { "description": "Structured daily details for this quota.", "properties": { "limit": { "description": "Maximum number of records requested or returned in one page of this daily.", "type": "integer" }, "remaining": { "description": "Numeric remaining reported for this daily.", "nullable": true, "type": "integer" }, "used": { "description": "Numeric used reported for this daily.", "type": "integer" } }, "required": [ "limit", "used", "remaining" ], "type": "object" }, "GeneratorQuotaSnapshot": { "description": "Structured quota details for this generator options response.", "nullable": true, "properties": { "budgets": { "$ref": "#/components/schemas/GeneratorQuotaBudgets" }, "daily": { "$ref": "#/components/schemas/GeneratorQuotaCounter" }, "nextDailyReliefAt": { "description": "Backwards-compatible alias of windowResetsAt.", "nullable": true, "type": "integer" }, "pending": { "$ref": "#/components/schemas/GeneratorQuotaCounter" }, "role": { "description": "Access role represented by this quota; use it for display and capability checks, not authentication.", "type": "string" }, "supporter": { "description": "Whether supporter applies to this quota.", "type": "boolean" }, "supporterPreview": { "description": "Structured supporter preview details for this quota.", "properties": { "budgets": { "$ref": "#/components/schemas/GeneratorQuotaBudgets" }, "daily": { "$ref": "#/components/schemas/GeneratorQuotaCounter" }, "pending": { "$ref": "#/components/schemas/GeneratorQuotaCounter" } }, "required": [ "daily", "pending", "budgets" ], "type": "object" }, "windowMs": { "description": "Personal usage period length in milliseconds.", "type": "integer" }, "windowResetsAt": { "description": "Epoch milliseconds when the current personal usage period resets and the full allowance returns.", "nullable": true, "type": "integer" }, "windowStartedAt": { "description": "Epoch milliseconds when the current personal usage period started, or null before first use / after reset.", "nullable": true, "type": "integer" } }, "required": [ "role", "supporter", "windowMs", "windowStartedAt", "windowResetsAt", "nextDailyReliefAt", "daily", "pending", "budgets", "supporterPreview" ], "type": "object" }, "GeneratorSafetySnapshot": { "description": "Fields describing generator safety snapshot in Developer API requests and responses.", "properties": { "error": { "description": "Error associated with this generator safety snapshot; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "outputs": { "additionalProperties": true, "description": "Structured outputs details for this generator safety snapshot.", "type": "object" }, "reason": { "description": "Reason associated with this generator safety snapshot; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "status": { "description": "Current lifecycle state of this generator safety snapshot; clients should tolerate future values. Supported values: `ok`, `quarantined`, `pending_review`.", "enum": [ "ok", "quarantined", "pending_review" ], "type": "string" }, "updatedAt": { "description": "Unix epoch timestamp in milliseconds.", "nullable": true, "type": "integer" } }, "type": "object" }, "GeneratorState": { "description": "Fields describing generator state in Developer API requests and responses.", "properties": { "allowModeratorsWhenDisabled": { "description": "Whether allow moderators when disabled applies to this generator state.", "type": "boolean" }, "enabled": { "description": "Whether enabled applies to this generator state.", "type": "boolean" }, "message": { "description": "Message associated with this generator state; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "regionalPromptsAdminsOnly": { "description": "Whether regional prompts admins only applies to this generator state.", "type": "boolean" } }, "required": [ "enabled", "message", "allowModeratorsWhenDisabled", "regionalPromptsAdminsOnly" ], "type": "object" }, "GeneratorStorageStatus": { "description": "Fields describing generator storage status in Developer API requests and responses.", "properties": { "errors": { "description": "Ordered errors entries included with this generator storage status; an empty list means none are available.", "items": { "description": "Structured errors item details for this errors.", "properties": { "error": { "description": "Error associated with this errors item; preserve server-returned values when passing them to another operation.", "type": "string" }, "path": { "description": "Server-provided path for the path associated with this errors item; treat it as opaque.", "type": "string" } }, "required": [ "path", "error" ], "type": "object" }, "type": "array" }, "status": { "description": "Current lifecycle state of this generator storage status; clients should tolerate future values.", "nullable": true, "type": "string" }, "storedAt": { "description": "Unix epoch timestamp in milliseconds.", "nullable": true, "type": "integer" } }, "required": [ "status", "storedAt", "errors" ], "type": "object" }, "GeneratorTagSuggestion": { "description": "Fields describing generator tag suggestion in Developer API requests and responses.", "properties": { "aliases": { "description": "Ordered aliases entries included with this generator tag suggestion; an empty list means none are available.", "items": { "description": "Aliases item associated with this aliases; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "count": { "description": "Number of count records represented by this generator tag suggestion.", "nullable": true, "type": "integer" }, "display": { "description": "Display associated with this generator tag suggestion; preserve server-returned values when passing them to another operation.", "type": "string" }, "name": { "description": "Human-readable name for this generator tag suggestion; it is not a stable identifier.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of generator tag suggestion; clients should tolerate future values.", "nullable": true, "type": "integer" } }, "required": [ "name", "display", "aliases" ], "type": "object" }, "GeneratorTagSuggestionsResponse": { "description": "Fields describing generator tag suggestions response in Developer API requests and responses.", "properties": { "tags": { "description": "Ordered tags entries included with this generator tag suggestions response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorTagSuggestion" }, "type": "array" } }, "required": [ "tags" ], "type": "object" }, "GeneratorUploadResponse": { "description": "Fields describing generator upload response in Developer API requests and responses.", "properties": { "expiresAt": { "description": "UTC timestamp for the expires at transition of this generator upload response. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "mimeType": { "description": "Discriminator identifying the kind of generator upload response; clients should tolerate future values.", "type": "string" }, "originalName": { "description": "Human-readable original name for this generator upload response; it is not a stable identifier.", "type": "string" }, "path": { "description": "Server-provided path for the path associated with this generator upload response; treat it as opaque.", "type": "string" }, "size": { "description": "Size of the associated generator upload response content in the unit indicated by the field name.", "type": "integer" }, "ttlSeconds": { "description": "Numeric ttl seconds reported for this generator upload response.", "type": "integer" } }, "required": [ "path", "mimeType", "size", "originalName", "expiresAt", "ttlSeconds" ], "type": "object" }, "GeneratorUploadTouchRequest": { "description": "Fields describing generator upload touch request in Developer API requests and responses.", "properties": { "paths": { "description": "Ordered paths entries included with this generator upload touch request; an empty list means none are available.", "items": { "description": "Paths item associated with this paths; preserve server-returned values when passing them to another operation.", "example": "generator/source-123.png", "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "paths" ], "type": "object" }, "GeneratorUploadTouchResponse": { "description": "Fields describing generator upload touch response in Developer API requests and responses.", "properties": { "expiresAt": { "description": "UTC timestamp for the expires at transition of this generator upload touch response. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "missing": { "description": "Ordered missing entries included with this generator upload touch response; an empty list means none are available.", "items": { "description": "Missing item associated with this missing; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "touched": { "description": "Numeric touched reported for this generator upload touch response. Minimum: 0.", "minimum": 0, "type": "integer" }, "ttlSeconds": { "description": "Numeric ttl seconds reported for this generator upload touch response.", "type": "integer" } }, "required": [ "touched", "missing", "expiresAt", "ttlSeconds" ], "type": "object" }, "GeneratorVideoAspectRatioOption": { "description": "Fields describing generator video aspect ratio option in Developer API requests and responses.", "properties": { "height": { "description": "Relative height for a fixed ratio.", "minimum": 1, "type": "integer" }, "id": { "description": "Aspect-ratio wire value.", "enum": [ "source", "1:1", "4:3", "3:4", "16:9", "9:16" ], "type": "string" }, "label": { "description": "Human-readable ratio label.", "type": "string" }, "sourceOnly": { "description": "Whether the option is restricted to image-to-video.", "type": "boolean" }, "width": { "description": "Relative width for a fixed ratio.", "minimum": 1, "type": "integer" } }, "required": [ "id", "label" ], "type": "object" }, "GeneratorVideoCapabilities": { "description": "Fields describing generator video capabilities in Developer API requests and responses.", "properties": { "audioOutput": { "description": "Whether synchronized audio generation is available.", "type": "boolean" }, "imageInput": { "description": "Whether image-to-video input is available.", "type": "boolean" }, "lastFrameInput": { "description": "Whether ending-frame conditioning is available.", "type": "boolean" }, "ready": { "description": "Whether the remote video runtime is ready for base generation.", "type": "boolean" } }, "required": [ "ready", "imageInput", "lastFrameInput", "audioOutput" ], "type": "object" }, "GeneratorVideoCreateBase": { "description": "Fields describing generator video create base in Developer API requests and responses.", "properties": { "audioEnabled": { "default": false, "description": "Request synchronized audio when the capability is available.", "type": "boolean" }, "negativePrompt": { "description": "Optional negative prompt; the server default is used when omitted.", "maxLength": 1000, "type": "string" }, "prompt": { "description": "Positive video prompt.", "maxLength": 8000, "minLength": 1, "type": "string" }, "promptPreset": { "description": "Optional server-provided prompt-preset ID.", "enum": [ "cinematic-scene", "product-orbit", "image-animation", "frame-transition" ], "nullable": true, "type": "string" }, "seed": { "description": "Optional safe non-negative decimal seed; generated when omitted.", "pattern": "^[0-9]{1,16}$", "type": "string" }, "sfwMode": { "description": "Apply stricter generator-only output moderation; mandatory minor-safety checks always apply.", "type": "boolean" }, "steps": { "default": 25, "description": "Sampling steps.", "maximum": 30, "minimum": 15, "type": "integer" } }, "required": [ "prompt" ], "type": "object" }, "GeneratorVideoCreateImage10Request": { "allOf": [ { "$ref": "#/components/schemas/GeneratorVideoCreateBase" }, { "description": "Fields describing generator video create image10 request in Developer API requests and responses.", "properties": { "aspectRatio": { "default": "source", "description": "Match the first frame by default or explicitly crop to a fixed ratio.", "enum": [ "source", "1:1", "4:3", "3:4", "16:9", "9:16" ], "type": "string" }, "frames": { "description": "Approximately ten seconds for two credits.", "enum": [ 243 ], "type": "integer" }, "lastFrameImagePath": { "description": "Optional owned generator-upload path used as Picture2.", "minLength": 1, "type": "string" }, "mode": { "description": "Image-to-video mode.", "enum": [ "image2video" ], "type": "string" }, "resolutionBucket": { "description": "Ten-second clips are limited to buckets up to 512.", "enum": [ 384, 512 ], "type": "integer" }, "sourceImagePath": { "description": "Active generator-upload path owned by the caller and used as Picture1.", "minLength": 1, "type": "string" } }, "required": [ "mode", "resolutionBucket", "frames", "sourceImagePath" ], "type": "object" } ], "description": "Approximately ten-second I2V request with a required first frame, optional last frame, and two-credit cost." }, "GeneratorVideoCreateImage5Request": { "allOf": [ { "$ref": "#/components/schemas/GeneratorVideoCreateBase" }, { "description": "Fields describing generator video create image5 request in Developer API requests and responses.", "properties": { "aspectRatio": { "default": "source", "description": "Match the first frame by default or explicitly crop to a fixed ratio.", "enum": [ "source", "1:1", "4:3", "3:4", "16:9", "9:16" ], "type": "string" }, "frames": { "default": 124, "description": "Approximately five seconds for one credit.", "enum": [ 124 ], "type": "integer" }, "lastFrameImagePath": { "description": "Optional owned generator-upload path used as Picture2.", "minLength": 1, "type": "string" }, "mode": { "description": "Image-to-video mode.", "enum": [ "image2video" ], "type": "string" }, "resolutionBucket": { "description": "Requested resolution bucket.", "enum": [ 384, 512, 640, 768 ], "type": "integer" }, "sourceImagePath": { "description": "Active generator-upload path owned by the caller and used as Picture1.", "minLength": 1, "type": "string" } }, "required": [ "mode", "resolutionBucket", "sourceImagePath" ], "type": "object" } ], "description": "Image-to-video request with a required first frame and optional last frame." }, "GeneratorVideoCreateRequest": { "description": "Mode- and duration-specific video request. Unsupported mode, source-frame, duration, and bucket combinations are excluded by the schema.", "oneOf": [ { "$ref": "#/components/schemas/GeneratorVideoCreateText5Request" }, { "$ref": "#/components/schemas/GeneratorVideoCreateText10Request" }, { "$ref": "#/components/schemas/GeneratorVideoCreateImage5Request" }, { "$ref": "#/components/schemas/GeneratorVideoCreateImage10Request" } ] }, "GeneratorVideoCreateText10Request": { "allOf": [ { "$ref": "#/components/schemas/GeneratorVideoCreateBase" }, { "description": "Fields describing generator video create text10 request in Developer API requests and responses.", "not": { "anyOf": [ { "required": [ "sourceImagePath" ] }, { "required": [ "lastFrameImagePath" ] } ] }, "properties": { "aspectRatio": { "default": "4:3", "description": "Fixed output ratio.", "enum": [ "1:1", "4:3", "3:4", "16:9", "9:16" ], "type": "string" }, "frames": { "description": "Approximately ten seconds for two credits.", "enum": [ 243 ], "type": "integer" }, "mode": { "description": "Text-to-video mode.", "enum": [ "txt2video" ], "type": "string" }, "resolutionBucket": { "description": "Ten-second clips are limited to buckets up to 512.", "enum": [ 384, 512 ], "type": "integer" } }, "required": [ "mode", "resolutionBucket", "frames" ], "type": "object" } ], "description": "Text-to-video request for approximately ten seconds and two credits." }, "GeneratorVideoCreateText5Request": { "allOf": [ { "$ref": "#/components/schemas/GeneratorVideoCreateBase" }, { "description": "Fields describing generator video create text5 request in Developer API requests and responses.", "not": { "anyOf": [ { "required": [ "sourceImagePath" ] }, { "required": [ "lastFrameImagePath" ] } ] }, "properties": { "aspectRatio": { "default": "4:3", "description": "Fixed output ratio.", "enum": [ "1:1", "4:3", "3:4", "16:9", "9:16" ], "type": "string" }, "frames": { "default": 124, "description": "Approximately five seconds for one credit.", "enum": [ 124 ], "type": "integer" }, "mode": { "description": "Text-to-video mode.", "enum": [ "txt2video" ], "type": "string" }, "resolutionBucket": { "description": "Requested resolution bucket.", "enum": [ 384, 512, 640, 768 ], "type": "integer" } }, "required": [ "mode", "resolutionBucket" ], "type": "object" } ], "description": "Text-to-video request for the default approximately five-second duration." }, "GeneratorVideoDefaults": { "description": "Fields describing generator video defaults in Developer API requests and responses.", "properties": { "aspectRatio": { "description": "Default text-to-video ratio.", "enum": [ "4:3" ], "type": "string" }, "audioEnabled": { "description": "Default synchronized-audio choice.", "type": "boolean" }, "cfg": { "description": "Default server-owned guidance value.", "type": "number" }, "fps": { "description": "Default output FPS.", "enum": [ 24 ], "type": "integer" }, "frames": { "description": "Default frame count.", "enum": [ 124 ], "type": "integer" }, "imageAspectRatio": { "description": "Default image-to-video ratio behavior.", "enum": [ "source" ], "type": "string" }, "mode": { "description": "Default mode.", "enum": [ "txt2video" ], "type": "string" }, "negativePrompt": { "description": "Default negative prompt.", "type": "string" }, "resolutionBucket": { "description": "Default resolution bucket.", "enum": [ 512 ], "type": "integer" }, "samplerName": { "description": "Default server-owned sampler.", "type": "string" }, "scheduler": { "description": "Default server-owned scheduler.", "type": "string" }, "sfwMode": { "description": "Current account's default SFW choice.", "type": "boolean" }, "steps": { "description": "Default sampling steps.", "maximum": 30, "minimum": 15, "type": "integer" } }, "required": [ "mode", "resolutionBucket", "aspectRatio", "imageAspectRatio", "frames", "fps", "steps", "cfg", "samplerName", "scheduler", "negativePrompt", "audioEnabled", "sfwMode" ], "type": "object" }, "GeneratorVideoDurationOption": { "description": "Fields describing generator video duration option in Developer API requests and responses.", "properties": { "creditCost": { "description": "Rolling-quota credits reserved by this duration.", "enum": [ 1, 2 ], "type": "integer" }, "durationSeconds": { "description": "Expected playback duration at the configured FPS.", "minimum": 0, "type": "number" }, "estimateFactor": { "description": "Server-side multiplier used for queue estimates.", "minimum": 1, "type": "number" }, "frames": { "description": "Requested workflow frame count.", "enum": [ 124, 243 ], "type": "integer" }, "label": { "description": "Human-readable approximate duration.", "type": "string" }, "maxResolutionBucket": { "description": "Largest bucket accepted for this duration.", "enum": [ 512, 768 ], "type": "integer" } }, "required": [ "frames", "label", "durationSeconds", "creditCost", "maxResolutionBucket", "estimateFactor" ], "type": "object" }, "GeneratorVideoEstimateModifiers": { "description": "Fields describing generator video estimate modifiers in Developer API requests and responses.", "properties": { "audio": { "description": "Audio render-time multiplier.", "minimum": 1, "type": "number" }, "defaultSteps": { "description": "Step count represented by base estimates.", "minimum": 1, "type": "integer" }, "imageToVideo": { "description": "I2V render-time multiplier.", "minimum": 1, "type": "number" }, "lastFrame": { "description": "Ending-frame render-time multiplier.", "minimum": 1, "type": "number" } }, "required": [ "defaultSteps", "imageToVideo", "lastFrame", "audio" ], "type": "object" }, "GeneratorVideoEstimateRange": { "description": "Fields describing generator video estimate range in Developer API requests and responses.", "properties": { "confidence": { "description": "Whether the estimate is a baseline or production-calibrated.", "enum": [ "baseline", "observed" ], "type": "string" }, "maxSeconds": { "description": "Upper calibrated render-time estimate, excluding queue delay.", "minimum": 0, "type": "integer" }, "minSeconds": { "description": "Lower calibrated render-time estimate, excluding queue delay.", "minimum": 0, "type": "integer" }, "sampleCount": { "description": "Production samples used for this calibration.", "minimum": 0, "type": "integer" } }, "required": [ "minSeconds", "maxSeconds", "sampleCount", "confidence" ], "type": "object" }, "GeneratorVideoJob": { "description": "Fields describing generator video job in Developer API requests and responses.", "properties": { "cfg": { "description": "Server-owned guidance value.", "type": "number" }, "completedAt": { "description": "Terminal completion time.", "format": "date-time", "nullable": true, "type": "string" }, "createdAt": { "description": "Creation time.", "format": "date-time", "type": "string" }, "creditCost": { "description": "Credits reserved by this job.", "enum": [ 1, 2 ], "type": "integer" }, "downloadUrl": { "description": "Authenticated MP4 attachment URL when available and viewable.", "nullable": true, "type": "string" }, "durationSeconds": { "description": "Expected playback duration.", "minimum": 0, "type": "number" }, "error": { "description": "Viewer-safe terminal error.", "nullable": true, "type": "string" }, "estimatedCompletionMs": { "description": "Estimated milliseconds from now until completion.", "format": "int64", "minimum": 0, "nullable": true, "type": "integer" }, "estimatedRemainingMs": { "description": "Estimated time until completion, including queue delay.", "format": "int64", "minimum": 0, "nullable": true, "type": "integer" }, "estimatedRenderMs": { "description": "Estimated render duration.", "format": "int64", "minimum": 0, "nullable": true, "type": "integer" }, "expiresAt": { "description": "Generated-output expiration time.", "format": "date-time", "nullable": true, "type": "string" }, "finalizationMs": { "description": "Download, validation, and moderation time.", "format": "int64", "nullable": true, "type": "integer" }, "firstFrameUrl": { "description": "Authenticated source-frame preview URL.", "nullable": true, "type": "string" }, "fps": { "description": "Output FPS.", "enum": [ 24 ], "type": "integer" }, "frames": { "description": "Requested frame count.", "enum": [ 124, 243 ], "type": "integer" }, "hasFirstFrame": { "description": "Whether the job has a source image.", "type": "boolean" }, "hasLastFrame": { "description": "Whether the job has an ending-frame image.", "type": "boolean" }, "height": { "description": "Resolved output height.", "minimum": 32, "type": "integer" }, "id": { "description": "Video job ID.", "format": "uuid", "type": "string" }, "lastFrameUrl": { "description": "Authenticated ending-frame preview URL.", "nullable": true, "type": "string" }, "metadata": { "$ref": "#/components/schemas/GeneratorVideoPublicMetadata" }, "mode": { "description": "Generation mode.", "enum": [ "txt2video", "image2video" ], "type": "string" }, "negativePrompt": { "description": "Submitted or server-default negative prompt.", "nullable": true, "type": "string" }, "outputBytes": { "description": "Final MP4 size.", "format": "int64", "nullable": true, "type": "integer" }, "outputDurationSeconds": { "description": "Media playback duration, not generation time.", "minimum": 0, "type": "number" }, "outputUrl": { "description": "Authenticated inline MP4 URL when available and viewable.", "nullable": true, "type": "string" }, "position": { "description": "Current one-based queue position.", "minimum": 1, "nullable": true, "type": "integer" }, "processingMs": { "description": "Worker processing time.", "format": "int64", "nullable": true, "type": "integer" }, "progress": { "description": "Normalized job progress.", "maximum": 1, "minimum": 0, "type": "number" }, "progressMessage": { "description": "Viewer-safe current phase.", "nullable": true, "type": "string" }, "prompt": { "description": "Submitted positive prompt.", "type": "string" }, "promptPreset": { "description": "Selected prompt-preset ID.", "nullable": true, "type": "string" }, "queueEtaMs": { "description": "Estimated wait before rendering begins.", "format": "int64", "minimum": 0, "nullable": true, "type": "integer" }, "queueWaitMs": { "description": "Time from creation until worker start.", "format": "int64", "nullable": true, "type": "integer" }, "remoteRenderMs": { "description": "Remote rendering time.", "format": "int64", "nullable": true, "type": "integer" }, "safety": { "$ref": "#/components/schemas/GeneratorVideoSafetySnapshot" }, "samplerName": { "description": "Server-owned sampler name.", "type": "string" }, "scheduler": { "description": "Server-owned scheduler name.", "type": "string" }, "seed": { "description": "Decimal generation seed.", "example": "42", "pattern": "^[0-9]{1,16}$", "type": "string" }, "startedAt": { "description": "Worker start time.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "Current job lifecycle status.", "enum": [ "queued", "running", "finalizing", "completed", "failed", "cancelled" ], "type": "string" }, "steps": { "description": "Sampling steps.", "maximum": 30, "minimum": 15, "type": "integer" }, "taggerTags": { "description": "Normalized sampled-frame tags.", "items": { "description": "Tagger Tags item associated with this tagger tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "totalElapsedMs": { "description": "Total creation-to-completion time.", "format": "int64", "nullable": true, "type": "integer" }, "width": { "description": "Resolved output width.", "minimum": 32, "type": "integer" } }, "required": [ "id", "mode", "status", "prompt", "negativePrompt", "promptPreset", "width", "height", "frames", "fps", "durationSeconds", "outputDurationSeconds", "creditCost", "steps", "cfg", "samplerName", "scheduler", "seed", "progress", "progressMessage", "error", "outputBytes", "outputUrl", "downloadUrl", "hasFirstFrame", "hasLastFrame", "firstFrameUrl", "lastFrameUrl", "metadata", "safety", "taggerTags", "queueWaitMs", "processingMs", "remoteRenderMs", "finalizationMs", "totalElapsedMs", "position", "queueEtaMs", "estimatedRenderMs", "estimatedRemainingMs", "estimatedCompletionMs", "createdAt", "startedAt", "completedAt", "expiresAt" ], "type": "object" }, "GeneratorVideoJobEnvelope": { "description": "Fields describing generator video job envelope in Developer API requests and responses.", "properties": { "job": { "$ref": "#/components/schemas/GeneratorVideoJob" } }, "required": [ "job" ], "type": "object" }, "GeneratorVideoJobListResponse": { "description": "Fields describing generator video job list response in Developer API requests and responses.", "properties": { "jobs": { "description": "Ordered jobs entries included with this generator video job list response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorVideoJob" }, "type": "array" }, "nextCursor": { "description": "Cursor for the next page.", "format": "uuid", "nullable": true, "type": "string" }, "quota": { "$ref": "#/components/schemas/GeneratorVideoQuota" } }, "required": [ "jobs", "nextCursor", "quota" ], "type": "object" }, "GeneratorVideoJobWithQuotaResponse": { "description": "Fields describing generator video job with quota response in Developer API requests and responses.", "properties": { "job": { "$ref": "#/components/schemas/GeneratorVideoJob" }, "quota": { "$ref": "#/components/schemas/GeneratorVideoQuota" } }, "required": [ "job", "quota" ], "type": "object" }, "GeneratorVideoLegacyResolution": { "deprecated": true, "description": "Fields describing generator video legacy resolution in Developer API requests and responses.", "properties": { "height": { "description": "Legacy canvas height.", "minimum": 1, "type": "integer" }, "id": { "description": "Legacy preset identifier.", "type": "string" }, "label": { "description": "Legacy preset label.", "type": "string" }, "width": { "description": "Legacy canvas width.", "minimum": 1, "type": "integer" } }, "required": [ "id", "label", "width", "height" ], "type": "object" }, "GeneratorVideoLimits": { "description": "Fields describing generator video limits in Developer API requests and responses.", "properties": { "cfg": { "description": "Server-owned guidance value.", "type": "number" }, "fps": { "description": "Output frames per second.", "enum": [ 24 ], "type": "integer" }, "frames": { "description": "Supported frame counts.", "items": { "description": "Numeric frames item reported for this frames. Supported values: `124`, `243`.", "enum": [ 124, 243 ], "type": "integer" }, "type": "array" }, "maxOutputBytes": { "description": "Maximum accepted generated-video size.", "format": "int64", "minimum": 1, "type": "integer" }, "maxPixels": { "description": "Maximum resolved canvas area in pixels.", "minimum": 1, "type": "integer" }, "maxSourceBytes": { "description": "Maximum bytes per source frame image.", "format": "int64", "minimum": 1, "type": "integer" }, "maxSourcePixels": { "description": "Maximum decoded pixels per source frame image.", "minimum": 1, "type": "integer" }, "maxSteps": { "description": "Maximum accepted sampling step count.", "minimum": 1, "type": "integer" }, "minSteps": { "description": "Minimum accepted sampling step count.", "minimum": 1, "type": "integer" }, "negativePromptChars": { "description": "Maximum negative-prompt length in characters.", "minimum": 1, "type": "integer" }, "promptChars": { "description": "Maximum prompt length in characters.", "minimum": 1, "type": "integer" }, "retentionDays": { "description": "Generated-output retention period in days.", "minimum": 1, "type": "integer" } }, "required": [ "promptChars", "negativePromptChars", "minSteps", "maxSteps", "maxPixels", "frames", "fps", "cfg", "maxSourceBytes", "maxSourcePixels", "maxOutputBytes", "retentionDays" ], "type": "object" }, "GeneratorVideoModeOption": { "description": "Fields describing generator video mode option in Developer API requests and responses.", "properties": { "enabled": { "description": "Whether the runtime currently supports this mode.", "type": "boolean" }, "id": { "description": "Wire value submitted as the job mode.", "enum": [ "txt2video", "image2video" ], "type": "string" }, "label": { "description": "Human-readable mode label.", "type": "string" }, "unavailableReason": { "description": "Viewer-safe explanation when the mode is unavailable.", "nullable": true, "type": "string" } }, "required": [ "id", "label", "enabled" ], "type": "object" }, "GeneratorVideoOptionsResponse": { "description": "Fields describing generator video options response in Developer API requests and responses.", "properties": { "aspectRatios": { "description": "Ordered aspect ratios entries included with this generator video options response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorVideoAspectRatioOption" }, "type": "array" }, "capabilities": { "$ref": "#/components/schemas/GeneratorVideoCapabilities" }, "defaults": { "$ref": "#/components/schemas/GeneratorVideoDefaults" }, "durationOptions": { "description": "Ordered duration options entries included with this generator video options response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorVideoDurationOption" }, "type": "array" }, "estimateModifiers": { "$ref": "#/components/schemas/GeneratorVideoEstimateModifiers" }, "limits": { "$ref": "#/components/schemas/GeneratorVideoLimits" }, "modes": { "description": "Ordered modes entries included with this generator video options response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorVideoModeOption" }, "type": "array" }, "promptPresets": { "description": "Ordered prompt presets entries included with this generator video options response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorVideoPromptPreset" }, "type": "array" }, "quota": { "$ref": "#/components/schemas/GeneratorVideoQuota" }, "resolutionBuckets": { "description": "Ordered resolution buckets entries included with this generator video options response; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorVideoResolutionBucketOption" }, "type": "array" }, "resolutions": { "deprecated": true, "description": "Former exact presets retained temporarily for cached product clients.", "items": { "$ref": "#/components/schemas/GeneratorVideoLegacyResolution" }, "type": "array" } }, "required": [ "modes", "limits", "durationOptions", "resolutionBuckets", "aspectRatios", "promptPresets", "defaults", "capabilities", "quota", "estimateModifiers" ], "type": "object" }, "GeneratorVideoPromptPreset": { "description": "Fields describing generator video prompt preset in Developer API requests and responses.", "properties": { "id": { "description": "Preset identifier submitted with a job.", "enum": [ "cinematic-scene", "product-orbit", "image-animation", "frame-transition" ], "type": "string" }, "label": { "description": "Human-readable preset name.", "type": "string" }, "prompt": { "description": "Server-maintained starting prompt.", "type": "string" } }, "required": [ "id", "label", "prompt" ], "type": "object" }, "GeneratorVideoPublicMetadata": { "description": "Fields describing generator video public metadata in Developer API requests and responses.", "properties": { "aspectRatio": { "description": "Requested ratio behavior.", "enum": [ "source", "1:1", "4:3", "3:4", "16:9", "9:16" ], "nullable": true, "type": "string" }, "audioEnabled": { "description": "Whether synchronized audio was requested.", "type": "boolean" }, "creditCost": { "description": "Credits reserved by the job.", "enum": [ 1, 2 ], "type": "integer" }, "resolutionBucket": { "description": "Requested resolution bucket.", "enum": [ 384, 512, 640, 768 ], "nullable": true, "type": "integer" }, "sfwMode": { "description": "Whether stricter generator-only output moderation was requested.", "type": "boolean" }, "sourceFit": { "description": "I2V source-image fit behavior.", "enum": [ "source", "crop" ], "nullable": true, "type": "string" } }, "required": [ "sfwMode", "audioEnabled", "resolutionBucket", "aspectRatio", "sourceFit", "creditCost" ], "type": "object" }, "GeneratorVideoQuota": { "description": "Fields describing generator video quota in Developer API requests and responses.", "properties": { "limit": { "description": "Credits available in the rolling window; zero denotes an unlimited quota.", "minimum": 0, "type": "integer" }, "pending": { "description": "Current queued, running, or finalizing job count.", "minimum": 0, "type": "integer" }, "pendingLimit": { "description": "Maximum concurrent non-terminal jobs for the resolved tier.", "minimum": 1, "type": "integer" }, "remaining": { "description": "Remaining credits, or null for an unlimited quota.", "minimum": 0, "nullable": true, "type": "integer" }, "resetAt": { "description": "Earliest time at which a currently reserved credit leaves the rolling window.", "format": "date-time", "type": "string" }, "tier": { "description": "Quota tier resolved from the account role and active support access.", "enum": [ "user", "artist", "supporter", "staff" ], "type": "string" }, "unlimitedOverride": { "description": "Whether an administrator's image-and-video unlimited override removed the daily quota. Queue concurrency still applies.", "type": "boolean" }, "used": { "description": "Credits reserved during the current rolling 24-hour window.", "minimum": 0, "type": "integer" } }, "required": [ "tier", "limit", "used", "remaining", "resetAt", "pending", "pendingLimit", "unlimitedOverride" ], "type": "object" }, "GeneratorVideoResolutionBucketOption": { "description": "Fields describing generator video resolution bucket option in Developer API requests and responses.", "properties": { "estimate": { "$ref": "#/components/schemas/GeneratorVideoEstimateRange" }, "label": { "description": "Human-readable quality label.", "type": "string" }, "value": { "description": "Nominal short-edge resolution bucket.", "enum": [ 384, 512, 640, 768 ], "type": "integer" } }, "required": [ "value", "label", "estimate" ], "type": "object" }, "GeneratorVideoSafetyOutput": { "description": "Fields describing generator video safety output in Developer API requests and responses.", "properties": { "blocklistMatches": { "description": "Tags matching blocklist rules.", "items": { "description": "Blocklist Matches item associated with this blocklist matches; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "blocklisted": { "description": "Whether the scan matched the configured blocklist.", "type": "boolean" }, "csam": { "description": "Whether the scan matched minor-safety rules.", "type": "boolean" }, "csamMinorMatches": { "description": "Tags matching minor indicators.", "items": { "description": "Csam Minor Matches item associated with this csam minor matches; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "csamSexualMatches": { "description": "Tags matching sexual-content indicators.", "items": { "description": "Csam Sexual Matches item associated with this csam sexual matches; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "error": { "description": "Output-specific scan error.", "type": "string" }, "nsfw": { "description": "Whether the scan matched NSFW rules.", "type": "boolean" }, "nsfwMatches": { "description": "Tags matching NSFW rules.", "items": { "description": "Nsfw Matches item associated with this nsfw matches; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "path": { "description": "Server-side output basename used as the scan key.", "type": "string" }, "rating": { "description": "Automated sampled-frame rating.", "nullable": true, "type": "string" }, "tags": { "description": "Normalized sampled-frame tags.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" } }, "required": [ "path", "rating", "tags", "nsfw", "blocklisted", "csam", "nsfwMatches", "blocklistMatches", "csamMinorMatches", "csamSexualMatches" ], "type": "object" }, "GeneratorVideoSafetyRestriction": { "description": "Fields describing generator video safety restriction in Developer API requests and responses.", "properties": { "error": { "description": "Viewer-safe restriction message.", "type": "string" }, "errorCode": { "description": "Stable safety restriction code.", "enum": [ "GENERATOR_OUTPUT_PENDING_REVIEW", "GENERATOR_OUTPUT_QUARANTINED", "GENERATOR_OUTPUT_UNSAFE_SFW" ], "type": "string" }, "safetyReason": { "description": "Current safety reason.", "nullable": true, "type": "string" }, "safetyStatus": { "description": "Current blocking safety state.", "enum": [ "pending_review", "quarantined" ], "type": "string" } }, "required": [ "errorCode", "error", "safetyStatus", "safetyReason" ], "type": "object" }, "GeneratorVideoSafetyReview": { "description": "Fields describing generator video safety review in Developer API requests and responses.", "properties": { "actorId": { "description": "Reviewing staff account ID.", "nullable": true, "type": "integer" }, "actorRole": { "description": "Reviewing staff role.", "nullable": true, "type": "string" }, "locked": { "description": "Whether automated rescans may replace this review.", "type": "boolean" }, "note": { "description": "Private moderator note.", "nullable": true, "type": "string" }, "reason": { "description": "Moderator-selected or free-form safety reason.", "nullable": true, "type": "string" }, "reviewedAt": { "description": "Review time in Unix milliseconds.", "format": "int64", "nullable": true, "type": "integer" }, "status": { "description": "Moderator-selected safety status.", "enum": [ "ok", "pending_review", "quarantined" ], "nullable": true, "type": "string" } }, "required": [ "status", "reason", "note", "actorId", "actorRole", "reviewedAt", "locked" ], "type": "object" }, "GeneratorVideoSafetySnapshot": { "description": "Fields describing generator video safety snapshot in Developer API requests and responses.", "properties": { "error": { "description": "Scan-level error.", "nullable": true, "type": "string" }, "outputs": { "additionalProperties": { "$ref": "#/components/schemas/GeneratorVideoSafetyOutput" }, "description": "Per-output sampled-frame scan results keyed by output basename.", "type": "object" }, "reason": { "description": "Current safety reason.", "nullable": true, "type": "string" }, "review": { "allOf": [ { "$ref": "#/components/schemas/GeneratorVideoSafetyReview" } ], "description": "Latest manual moderation decision.", "nullable": true }, "sfwMode": { "description": "Whether stricter SFW output handling applied.", "type": "boolean" }, "status": { "description": "Current normalized safety status.", "enum": [ "ok", "pending_review", "quarantined" ], "nullable": true, "type": "string" }, "updatedAt": { "description": "Latest safety update in Unix milliseconds.", "format": "int64", "nullable": true, "type": "integer" } }, "required": [ "status", "reason", "outputs", "error", "updatedAt", "review" ], "type": "object" }, "GeneratorVideoSseConnectedEvent": { "description": "Fields describing generator video sse connected event in Developer API requests and responses.", "properties": { "ok": { "description": "Confirms that the authenticated event stream is connected.", "enum": [ true ], "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "GeneratorVideoSseHeartbeatEvent": { "description": "Fields describing generator video sse heartbeat event in Developer API requests and responses.", "properties": { "ts": { "description": "Server time in Unix milliseconds.", "format": "int64", "type": "integer" } }, "required": [ "ts" ], "type": "object" }, "GeneratorVideoSseJobEvent": { "description": "Fields describing generator video sse job event in Developer API requests and responses.", "properties": { "job": { "$ref": "#/components/schemas/GeneratorVideoJob" } }, "required": [ "job" ], "type": "object" }, "GeneratorVideoState": { "description": "Fields describing generator video state in Developer API requests and responses.", "properties": { "audience": { "description": "Staff-visible audience policy returned only to moderators and administrators.", "enum": [ "staff", "creators", "all" ], "type": "string" }, "canEnqueue": { "description": "Whether the current account can enqueue a video job now.", "type": "boolean" }, "enabled": { "description": "Whether new video jobs are globally enabled.", "type": "boolean" }, "message": { "description": "Viewer-facing lock message when generation is disabled.", "nullable": true, "type": "string" }, "staffOnly": { "description": "Staff-visible policy detail returned only to moderators and administrators.", "type": "boolean" }, "visible": { "description": "Whether the current account may see the video generator.", "type": "boolean" } }, "required": [ "visible", "enabled", "canEnqueue", "message" ], "type": "object" }, "Image": { "description": "Structured images item details for this images.", "example": { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" }, "properties": { "cfg": { "description": "Numeric cfg reported for this images item.", "type": "number" }, "createdAt": { "description": "UTC timestamp when this images item was created. Format: date-time.", "format": "date-time", "type": "string" }, "description": { "description": "User-facing description of this images item; it may contain an empty string when no description was supplied.", "type": "string" }, "dislikeCount": { "description": "Number of dislike records represented by this images item.", "type": "number" }, "fileName": { "description": "Human-readable file name for this images item; it is not a stable identifier.", "type": "string" }, "filePath": { "description": "Server-provided path for the file path associated with this images item; treat it as opaque.", "type": "string" }, "heartCount": { "description": "Number of heart records represented by this images item.", "type": "number" }, "id": { "description": "Stable identifier for the images item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "likeCount": { "description": "Number of like records represented by this images item.", "type": "number" }, "metadata": { "description": "Metadata associated with this images item; preserve server-returned values when passing them to another operation.", "type": "string" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this images item; availability depends on visibility and privacy rules.", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this images item; availability depends on visibility and privacy rules.", "type": "string" }, "rating": { "description": "Content-safety rating assigned to this images item; callers must still apply their own audience policy.", "type": "string" }, "sampler": { "description": "Sampler associated with this images item; preserve server-returned values when passing them to another operation.", "type": "string" }, "seed": { "description": "Numeric seed reported for this images item.", "type": "number" }, "steps": { "description": "Numeric steps reported for this images item.", "type": "number" }, "title": { "description": "Display title shown to users for this images item.", "type": "string" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this images item. Format: date-time.", "format": "date-time", "type": "string" } }, "type": "object" }, "ImageSpatialAttribution": { "description": "Fields describing image spatial attribution in Developer API requests and responses.", "properties": { "algorithmVersion": { "description": "Algorithm Version associated with this image spatial attribution; preserve server-returned values when passing them to another operation.", "type": "string" }, "atlasUrl": { "description": "URL for the atlas url associated with this image spatial attribution; do not persist temporary signed query parameters.", "type": "string" }, "columns": { "description": "Numeric columns reported for this image spatial attribution.", "type": "integer" }, "completedAt": { "description": "UTC timestamp for the completed at transition of this image spatial attribution. Format: date-time.", "format": "date-time", "type": "string" }, "device": { "description": "Device associated with this image spatial attribution; preserve server-returned values when passing them to another operation. Supported values: `cuda`, `cpu`, `cpu-fallback`.", "enum": [ "cuda", "cpu", "cpu-fallback" ], "type": "string" }, "durationMs": { "description": "Numeric duration ms reported for this image spatial attribution.", "type": "number" }, "height": { "description": "Numeric height reported for this image spatial attribution.", "type": "integer" }, "mapSize": { "description": "Numeric map size reported for this image spatial attribution.", "type": "integer" }, "message": { "description": "Message associated with this image spatial attribution; preserve server-returned values when passing them to another operation.", "type": "string" }, "modelVersion": { "description": "Model Version associated with this image spatial attribution; preserve server-returned values when passing them to another operation.", "type": "string" }, "requestAccess": { "description": "Structured request access details for this image spatial attribution.", "properties": { "accessTier": { "description": "Access Tier associated with this request access; preserve server-returned values when passing them to another operation. Supported values: `ANONYMOUS`, `STANDARD`, `SUPPORTER`, `STAFF`.", "enum": [ "ANONYMOUS", "STANDARD", "SUPPORTER", "STAFF" ], "type": "string" }, "canRequest": { "description": "Whether can request applies to this request access.", "type": "boolean" }, "freeLimit": { "description": "Numeric free limit reported for this request access.", "type": "integer" }, "reason": { "description": "Reason associated with this request access; preserve server-returned values when passing them to another operation. Supported values: `AUTH_REQUIRED`, `FREE_LIMIT_REACHED`.", "enum": [ "AUTH_REQUIRED", "FREE_LIMIT_REACHED" ], "type": "string" }, "remaining": { "description": "Numeric remaining reported for this request access.", "nullable": true, "type": "integer" } }, "type": "object" }, "requestedAt": { "description": "UTC timestamp for the requested at transition of this image spatial attribution. Format: date-time.", "format": "date-time", "type": "string" }, "retryAfterMs": { "description": "Numeric retry after ms reported for this image spatial attribution. Minimum: 0.", "minimum": 0, "type": "integer" }, "rows": { "description": "Numeric rows reported for this image spatial attribution.", "type": "integer" }, "status": { "description": "Current lifecycle state of this image spatial attribution; clients should tolerate future values. Supported values: `disabled`, `locked`, `unavailable`, `queued`, `processing`, `ready`, `failed`.", "enum": [ "disabled", "locked", "unavailable", "queued", "processing", "ready", "failed" ], "type": "string" }, "tags": { "description": "Ordered tags entries included with this image spatial attribution; an empty list means none are available.", "items": { "description": "Structured tags item details for this tags.", "properties": { "distribution": { "description": "Distribution associated with this tags item; preserve server-returned values when passing them to another operation. Supported values: `localized`, `mixed`, `distributed`.", "enum": [ "localized", "mixed", "distributed" ], "type": "string" }, "focus": { "description": "Numeric focus reported for this tags item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "index": { "description": "Numeric index reported for this tags item. Minimum: 0.", "minimum": 0, "type": "integer" }, "name": { "description": "Human-readable name for this tags item; it is not a stable identifier.", "type": "string" }, "score": { "description": "Numeric score reported for this tags item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "name", "score", "index", "focus", "distribution" ], "type": "object" }, "maxItems": 64, "type": "array" }, "width": { "description": "Numeric width reported for this image spatial attribution.", "type": "integer" } }, "required": [ "status" ], "type": "object" }, "Model": { "description": "Fields describing model in Developer API requests and responses.", "example": { "description": "

Overview

This is an example model.

", "descriptionImages": [], "id": 1, "tags": [ { "id": 1, "name": "example" } ], "title": "Example Model", "type": "LORA", "uploader": { "email": "user@example.com", "id": 2, "username": "exampleUser" }, "uploaderId": 2, "versions": [] }, "properties": { "description": { "description": "Sanitized rich HTML model description. Existing legacy Markdown remains render-compatible during migration.", "type": "string" }, "descriptionImages": { "description": "Ordered description images entries included with this model; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ModelDescriptionImage" }, "type": "array" }, "id": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "type": "integer" }, "tags": { "description": "Ordered tags entries included with this model; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Tag" }, "type": "array" }, "title": { "description": "Display title shown to users for this model.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of model; clients should tolerate future values.", "type": "string" }, "uploader": { "$ref": "#/components/schemas/User" }, "uploaderId": { "description": "Stable identifier for the uploader; use it in subsequent API calls instead of a display name.", "type": "integer" }, "versions": { "description": "Ordered versions entries included with this model; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Version" }, "type": "array" } }, "type": "object" }, "ModelDescriptionImage": { "description": "Structured description images item details for this description images.", "properties": { "createdAt": { "description": "UTC timestamp when this description images item was created. Format: date-time.", "format": "date-time", "type": "string" }, "fileName": { "description": "Human-readable file name for this description images item; it is not a stable identifier.", "type": "string" }, "filePath": { "description": "Server-provided path for the file path associated with this description images item; treat it as opaque.", "type": "string" }, "height": { "description": "Numeric height reported for this description images item.", "nullable": true, "type": "integer" }, "id": { "description": "Stable identifier for the description images item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "type": "integer" }, "rating": { "description": "Content-safety rating assigned to this description images item; callers must still apply their own audience policy.", "nullable": true, "type": "string" }, "variants": { "description": "Ordered variants entries included with this description images item; an empty list means none are available.", "items": { "description": "Structured variants item details for this variants.", "properties": { "bytes": { "description": "Size of the associated variants item content in the unit indicated by the field name.", "nullable": true, "type": "integer" }, "format": { "description": "Format associated with this variants item; preserve server-returned values when passing them to another operation.", "type": "string" }, "height": { "description": "Numeric height reported for this variants item.", "nullable": true, "type": "integer" }, "label": { "description": "Label associated with this variants item; preserve server-returned values when passing them to another operation.", "type": "string" }, "path": { "description": "Server-provided path for the path associated with this variants item; treat it as opaque.", "type": "string" }, "width": { "description": "Numeric width reported for this variants item.", "nullable": true, "type": "integer" } }, "type": "object" }, "nullable": true, "type": "array" }, "width": { "description": "Numeric width reported for this description images item.", "nullable": true, "type": "integer" } }, "type": "object" }, "ModelGalleryMediaEntry": { "description": "One mixed-media gallery entry. Use kind as the discriminator before reading data.", "properties": { "data": { "description": "Image or video metadata for this gallery entry.", "oneOf": [ { "$ref": "#/components/schemas/Image" }, { "$ref": "#/components/schemas/Video" } ] }, "kind": { "description": "Media type contained in data.", "enum": [ "image", "video" ], "type": "string" } }, "required": [ "kind", "data" ], "type": "object" }, "ModelGalleryResponse": { "description": "Stable paginated response envelope for a model's visible image and video gallery.", "properties": { "data": { "description": "Mixed image and video entries for the current page.", "items": { "$ref": "#/components/schemas/ModelGalleryMediaEntry" }, "type": "array" }, "limit": { "description": "Requested page size after server clamping.", "maximum": 30, "minimum": 1, "type": "integer" }, "page": { "description": "Current one-based page.", "minimum": 1, "type": "integer" }, "pinned": { "description": "Creator-pinned visible images. Present only on the first page when pins exist.", "items": { "$ref": "#/components/schemas/Image" }, "type": "array" }, "totalCount": { "description": "Total number of matching image and video entries.", "minimum": 0, "type": "integer" }, "totalPages": { "description": "Total number of pages at the current limit.", "minimum": 0, "type": "integer" } }, "required": [ "page", "limit", "totalCount", "totalPages", "data" ], "type": "object" }, "ModelVersionChunkUploadError": { "additionalProperties": true, "description": "Fields describing model version chunk upload error in Developer API requests and responses.", "properties": { "error": { "description": "Human-readable error message.", "example": "Chunk 0 must be 8388608 bytes", "type": "string" }, "errorCode": { "description": "Stable machine-readable code when the error has one.", "example": "UPLOAD_CHUNK_ABORTED", "type": "string" }, "retryable": { "description": "Whether retrying the idempotent operation is safe and expected.", "example": true, "type": "boolean" } }, "required": [ "error" ], "type": "object" }, "ModelVersionChunkUploadSession": { "description": "Fields describing model version chunk upload session in Developer API requests and responses.", "properties": { "chunkSize": { "description": "Negotiated non-final chunk length in bytes. Clients must use this returned value.", "format": "int64", "maximum": 90000000, "minimum": 8388608, "type": "integer" }, "createdAt": { "description": "UTC timestamp when this model version chunk upload session was created. Format: date-time.", "format": "date-time", "type": "string" }, "error": { "description": "Processing failure message when `status` is `error`; otherwise `null`.", "nullable": true, "type": "string" }, "expiresAt": { "description": "Fixed expiry set 24 hours after creation; chunk uploads do not extend it.", "format": "date-time", "type": "string" }, "fileSize": { "description": "Expected total file length in bytes.", "format": "int64", "maximum": 536870912, "minimum": 1, "type": "integer" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name. Minimum: 1.", "minimum": 1, "type": "integer" }, "originalName": { "description": "Path-stripped base name supplied when the session was created.", "type": "string" }, "receivedBytes": { "description": "Sum of valid staged chunk lengths.", "format": "int64", "maximum": 536870912, "minimum": 0, "type": "integer" }, "receivedChunks": { "description": "Zero-based indices of chunks currently stored with the expected byte length.", "items": { "description": "Numeric received chunks item reported for this received chunks. Minimum: 0.", "minimum": 0, "type": "integer" }, "type": "array" }, "status": { "$ref": "#/components/schemas/ModelVersionChunkUploadStatus" }, "totalChunks": { "description": "`ceil(fileSize / chunkSize)`.", "maximum": 128, "minimum": 1, "type": "integer" }, "updatedAt": { "description": "Time of the latest manifest update.", "format": "date-time", "type": "string" }, "uploadId": { "description": "Stable identifier used by all later upload operations.", "format": "uuid", "type": "string" }, "versionId": { "description": "Created model-version ID when `status` is `completed`; otherwise `null`.", "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "uploadId", "modelId", "originalName", "fileSize", "chunkSize", "totalChunks", "receivedChunks", "receivedBytes", "status", "versionId", "error", "createdAt", "updatedAt", "expiresAt" ], "type": "object" }, "ModelVersionChunkUploadStatus": { "description": "`created` has no valid chunks; `uploading` has at least one; `processing` is assembling/creating the version; `completed`, `error`, and `cancelled` are terminal for polling.", "enum": [ "created", "uploading", "processing", "completed", "error", "cancelled" ], "type": "string" }, "ModelVersionExternalResource": { "allOf": [ { "$ref": "#/components/schemas/ModelVersionResourceBase" }, { "description": "Structured external item details for this external.", "properties": { "baseModel": { "description": "Base Model associated with this external item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "downloadUrl": { "description": "URL for the download url associated with this external item; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "nullable": true, "type": "string" }, "externalResourceId": { "description": "Stable identifier for the external resource; use it in subsequent API calls instead of a display name.", "type": "integer" }, "fileName": { "description": "Human-readable file name for this external item; it is not a stable identifier.", "nullable": true, "type": "string" }, "modelType": { "description": "Discriminator identifying the kind of external item; clients should tolerate future values.", "nullable": true, "type": "string" }, "provider": { "description": "Provider associated with this external item; preserve server-returned values when passing them to another operation.", "type": "string" }, "title": { "description": "Display title shown to users for this external item.", "type": "string" }, "url": { "description": "URL for the url associated with this external item; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "type": "string" }, "versionName": { "description": "Human-readable version name for this external item; it is not a stable identifier.", "nullable": true, "type": "string" } }, "required": [ "externalResourceId", "provider", "title", "url" ], "type": "object" } ], "description": "External item associated with this external; preserve server-returned values when passing them to another operation." }, "ModelVersionListResponse": { "description": "Stable response envelope for versions visible to the current caller.", "properties": { "versions": { "description": "Versions visible to the current caller in the model's configured order.", "items": { "$ref": "#/components/schemas/Version" }, "type": "array" } }, "required": [ "versions" ], "type": "object" }, "ModelVersionLocalResource": { "allOf": [ { "$ref": "#/components/schemas/ModelVersionResourceBase" }, { "description": "Structured required item details for this required.", "properties": { "baseModel": { "description": "Base Model associated with this required item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "downloadUrl": { "description": "Null when the caller cannot download the target version.", "nullable": true, "type": "string" }, "fileName": { "description": "Human-readable file name for this required item; it is not a stable identifier.", "nullable": true, "type": "string" }, "fileScanStatus": { "description": "Current lifecycle state of this required item; clients should tolerate future values.", "nullable": true, "type": "string" }, "fileSizeKb": { "description": "Size of the associated required item content in the unit indicated by the field name.", "nullable": true, "type": "integer" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "type": "integer" }, "modelType": { "description": "Discriminator identifying the kind of required item; clients should tolerate future values.", "type": "string" }, "openUrl": { "description": "URL for the open url associated with this required item; do not persist temporary signed query parameters.", "type": "string" }, "previewImage": { "allOf": [ { "$ref": "#/components/schemas/ModelVersionResourcePreviewImage" } ], "description": "Preview Image associated with this required item; preserve server-returned values when passing them to another operation.", "nullable": true }, "publishAt": { "description": "UTC publication time for this required item; a future value indicates scheduled publication. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "title": { "description": "Display title shown to users for this required item.", "type": "string" }, "versionId": { "description": "Stable identifier for the version; use it in subsequent API calls instead of a display name.", "type": "integer" }, "versionName": { "description": "Human-readable version name for this required item; it is not a stable identifier.", "type": "string" }, "versionStatus": { "description": "Current lifecycle state of this required item; clients should tolerate future values.", "type": "string" } }, "required": [ "modelId", "versionId", "title", "versionName", "modelType", "versionStatus", "openUrl" ], "type": "object" } ], "description": "Required item associated with this required; preserve server-returned values when passing them to another operation." }, "ModelVersionMediaPreviewEntry": { "description": "Structured entries item details for this entries.", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Image" }, { "$ref": "#/components/schemas/Video" } ], "description": "Visible image or video metadata. Scheduled video records may have private generation fields redacted." }, "kind": { "description": "Media kind. Current values are image and video; clients must tolerate additions.", "type": "string" }, "origin": { "description": "Media origin. Current values are version and community; clients must tolerate additions.", "type": "string" } }, "required": [ "kind", "origin", "data" ], "type": "object" }, "ModelVersionMediaPreviewResponse": { "description": "Lightweight visible media grouped by model version for carousel and picker integrations.", "properties": { "limit": { "description": "Maximum entries returned per version after server clamping.", "maximum": 12, "minimum": 1, "type": "integer" }, "modelId": { "description": "Model whose versions were queried.", "type": "integer" }, "versions": { "description": "Ordered versions entries included with this model version media preview response; an empty list means none are available.", "items": { "description": "Structured versions item details for this versions.", "properties": { "entries": { "description": "Ordered entries entries included with this versions item; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ModelVersionMediaPreviewEntry" }, "type": "array" }, "id": { "description": "Model version identifier.", "type": "integer" } }, "required": [ "id", "entries" ], "type": "object" }, "type": "array" } }, "required": [ "modelId", "limit", "versions" ], "type": "object" }, "ModelVersionResourceBase": { "description": "Structured required item details for this required.", "properties": { "confidence": { "description": "Numeric confidence reported for this required item. Format: double.", "format": "double", "type": "number" }, "edgeId": { "description": "Stable identifier for the edge; use it in subsequent API calls instead of a display name.", "type": "integer" }, "evidence": { "description": "Source-specific evidence. New evidence fields may be added without a contract change.", "nullable": true, "type": "object" }, "id": { "description": "Stable identifier for the required item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "kind": { "description": "Dependency kind such as REQUIRED, RECOMMENDED, COMPATIBLE, or SAMPLE_USED.", "type": "string" }, "management": { "description": "Present only for a caller allowed to manage this resource graph.", "properties": { "createdAt": { "description": "UTC timestamp when this management was created. Format: date-time.", "format": "date-time", "type": "string" }, "createdById": { "description": "Stable identifier for the created by; use it in subsequent API calls instead of a display name.", "nullable": true, "type": "integer" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this management. Format: date-time.", "format": "date-time", "type": "string" } }, "required": [ "createdById", "createdAt", "updatedAt" ], "type": "object" }, "source": { "description": "Discovery source such as IMAGE_METADATA, IMPORTER_WEBHOOK, MANUAL, or SYSTEM.", "type": "string" }, "status": { "description": "Current values are ACTIVE and HIDDEN; clients must tolerate additions.", "type": "string" }, "strength": { "description": "Numeric strength reported for this required item. Format: double.", "format": "double", "type": "number" }, "targetType": { "description": "Current values are local and external; clients must tolerate additions.", "type": "string" } }, "required": [ "id", "edgeId", "targetType", "kind", "source", "status", "confidence", "strength", "evidence" ], "type": "object" }, "ModelVersionResourceGraphResponse": { "description": "Visible local and external dependencies associated with one model version.", "properties": { "canManage": { "description": "Whether the current caller may see hidden edges and management metadata.", "type": "boolean" }, "counts": { "description": "Structured counts details for this model version resource graph response.", "properties": { "detected": { "description": "Numeric detected reported for this counts. Minimum: 0.", "minimum": 0, "type": "integer" }, "external": { "description": "Numeric external reported for this counts. Minimum: 0.", "minimum": 0, "type": "integer" }, "hidden": { "description": "Numeric hidden reported for this counts. Minimum: 0.", "minimum": 0, "type": "integer" }, "local": { "description": "Numeric local reported for this counts. Minimum: 0.", "minimum": 0, "type": "integer" } }, "required": [ "detected", "local", "external", "hidden" ], "type": "object" }, "groups": { "description": "Structured groups details for this model version resource graph response.", "properties": { "compatible": { "description": "Ordered compatible entries included with this groups; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ModelVersionLocalResource" }, "type": "array" }, "external": { "description": "Ordered external entries included with this groups; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ModelVersionExternalResource" }, "type": "array" }, "recommended": { "description": "Ordered recommended entries included with this groups; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ModelVersionLocalResource" }, "type": "array" }, "required": { "description": "Ordered required entries included with this groups; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ModelVersionLocalResource" }, "type": "array" }, "sampleUsed": { "description": "Ordered sample used entries included with this groups; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ModelVersionLocalResource" }, "type": "array" } }, "required": [ "required", "recommended", "compatible", "sampleUsed", "external" ], "type": "object" }, "sourceVersionId": { "description": "Stable identifier for the source version; use it in subsequent API calls instead of a display name.", "type": "integer" } }, "required": [ "sourceVersionId", "canManage", "groups", "counts" ], "type": "object" }, "ModelVersionResourcePreviewImage": { "description": "Structured preview image details for this required item.", "properties": { "filePath": { "description": "Server-provided path for the file path associated with this preview image; treat it as opaque.", "nullable": true, "type": "string" }, "height": { "description": "Numeric height reported for this preview image.", "nullable": true, "type": "integer" }, "id": { "description": "Stable identifier for the preview image; use it in subsequent API calls instead of a display name.", "type": "integer" }, "rating": { "description": "Content-safety rating assigned to this preview image; callers must still apply their own audience policy.", "nullable": true, "type": "string" }, "variants": { "description": "Generated image variants as stored for the public image response.", "items": { "description": "Structured variants item details for this variants.", "type": "object" }, "nullable": true, "type": "array" }, "width": { "description": "Numeric width reported for this preview image.", "nullable": true, "type": "integer" } }, "required": [ "id", "filePath", "variants", "rating", "width", "height" ], "type": "object" }, "SelfProfile": { "description": "Fields describing self profile in Developer API requests and responses.", "example": { "apiKeys": [], "articleCount": 1, "bio": "Hello, I'm John.", "civitaiApiKey": null, "createdAt": "2025-02-26T10:00:00Z", "dateFormat": "yyyy-MM-dd HH:mm", "discordLinked": true, "email": "john@example.com", "followersCount": 5, "hasCivitaiApiKey": true, "id": 1, "imageCount": 20, "isFollowed": false, "modelCount": 10, "profileBanner": "banners/john_banner.jpg", "profilePicture": "profile/john_doe.png", "role": "USER", "sfwMode": false, "socialLinks": [], "trackDownloads": true, "uploads": { "articles": [], "images": [], "models": [], "videos": [] }, "username": "john_doe", "videoCount": 3 }, "properties": { "apiKeys": { "description": "Ordered api keys entries included with this self profile; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ApiKey" }, "type": "array" }, "articleCount": { "description": "Number of article records represented by this self profile.", "type": "integer" }, "bio": { "description": "Bio associated with this self profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "civitaiApiKey": { "description": "Always null because the encrypted Civitai credential is write-only.", "nullable": true, "readOnly": true, "type": "string" }, "createdAt": { "description": "UTC timestamp when this self profile was created. Format: date-time.", "format": "date-time", "type": "string" }, "dateFormat": { "description": "Date Format associated with this self profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "discordLinked": { "description": "Whether discord linked applies to this self profile.", "type": "boolean" }, "email": { "description": "Email associated with this self profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "followersCount": { "description": "Number of followers records represented by this self profile.", "type": "integer" }, "hasCivitaiApiKey": { "description": "Whether a Civitai API key is configured.", "type": "boolean" }, "id": { "description": "Stable identifier for the self profile; use it in subsequent API calls instead of a display name.", "type": "integer" }, "imageCount": { "description": "Number of image records represented by this self profile.", "type": "integer" }, "isFollowed": { "description": "Whether is followed applies to this self profile.", "type": "boolean" }, "modelCount": { "description": "Number of model records represented by this self profile.", "type": "integer" }, "profileBanner": { "description": "Profile Banner associated with this self profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "profilePicture": { "description": "Profile Picture associated with this self profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "role": { "description": "Access role represented by this self profile; use it for display and capability checks, not authentication.", "type": "string" }, "sfwMode": { "description": "Whether sfw mode applies to this self profile.", "type": "boolean" }, "socialLinks": { "description": "Ordered social links entries included with this self profile; an empty list means none are available.", "items": { "description": "Structured social links item details for this social links.", "properties": { "icon": { "description": "Icon associated with this social links item; preserve server-returned values when passing them to another operation.", "type": "string" }, "id": { "description": "Stable identifier for the social links item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "order": { "description": "Numeric order reported for this social links item.", "type": "integer" }, "url": { "description": "URL for the url associated with this social links item; do not persist temporary signed query parameters.", "type": "string" } }, "type": "object" }, "type": "array" }, "trackDownloads": { "description": "Whether track downloads applies to this self profile.", "type": "boolean" }, "uploads": { "$ref": "#/components/schemas/Uploads" }, "username": { "description": "Username associated with this self profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "videoCount": { "description": "Number of video records represented by this self profile.", "type": "integer" } }, "type": "object" }, "Tag": { "description": "Structured tags item details for this tags.", "example": { "id": 1, "name": "example" }, "properties": { "id": { "description": "Stable identifier for the tags item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "name": { "description": "Human-readable name for this tags item; it is not a stable identifier.", "type": "string" } }, "type": "object" }, "Uploads": { "description": "Structured uploads details for this self profile.", "properties": { "articles": { "description": "Ordered articles entries included with this uploads; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ApiKey" }, "type": "array" }, "images": { "description": "Ordered images entries included with this uploads; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ApiKey" }, "type": "array" }, "models": { "description": "Ordered models entries included with this uploads; an empty list means none are available.", "items": { "$ref": "#/components/schemas/User" }, "type": "array" }, "videos": { "description": "Ordered videos entries included with this uploads; an empty list means none are available.", "items": { "$ref": "#/components/schemas/ApiKey" }, "type": "array" } }, "type": "object" }, "User": { "description": "Structured uploader details for this video.", "example": { "email": "user@example.com", "id": 2, "profilePicture": "profile/john_doe.png", "role": "USER", "username": "exampleUser" }, "properties": { "email": { "description": "Email associated with this uploader; preserve server-returned values when passing them to another operation.", "type": "string" }, "id": { "description": "Stable identifier for the uploader; use it in subsequent API calls instead of a display name.", "type": "integer" }, "profilePicture": { "description": "Profile Picture associated with this uploader; preserve server-returned values when passing them to another operation.", "type": "string" }, "role": { "description": "Access role represented by this uploader; use it for display and capability checks, not authentication.", "type": "string" }, "username": { "description": "Username associated with this uploader; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" }, "UserProfile": { "description": "Fields describing user profile in Developer API requests and responses.", "example": { "articleCount": 1, "bio": "Hello, I'm John.", "createdAt": "2025-02-26T10:00:00Z", "followersCount": 5, "id": 1, "imageCount": 20, "isFollowed": false, "modelCount": 10, "profileBanner": "banners/john_banner.jpg", "profilePicture": "profile/john_doe.png", "role": "USER", "socialLinks": [], "username": "john_doe", "videoCount": 3 }, "properties": { "articleCount": { "description": "Number of article records represented by this user profile.", "type": "integer" }, "bio": { "description": "Bio associated with this user profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "createdAt": { "description": "UTC timestamp when this user profile was created. Format: date-time.", "format": "date-time", "type": "string" }, "followersCount": { "description": "Number of followers records represented by this user profile.", "type": "integer" }, "id": { "description": "Stable identifier for the user profile; use it in subsequent API calls instead of a display name.", "type": "integer" }, "imageCount": { "description": "Number of image records represented by this user profile.", "type": "integer" }, "isFollowed": { "description": "Whether is followed applies to this user profile.", "type": "boolean" }, "modelCount": { "description": "Number of model records represented by this user profile.", "type": "integer" }, "profileBanner": { "description": "Profile Banner associated with this user profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "profilePicture": { "description": "Profile Picture associated with this user profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "role": { "description": "Access role represented by this user profile; use it for display and capability checks, not authentication.", "type": "string" }, "socialLinks": { "description": "Ordered social links entries included with this user profile; an empty list means none are available.", "items": { "description": "Structured social links item details for this social links.", "properties": { "icon": { "description": "Icon associated with this social links item; preserve server-returned values when passing them to another operation.", "type": "string" }, "id": { "description": "Stable identifier for the social links item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "order": { "description": "Numeric order reported for this social links item.", "type": "integer" }, "url": { "description": "URL for the url associated with this social links item; do not persist temporary signed query parameters.", "type": "string" } }, "type": "object" }, "type": "array" }, "username": { "description": "Username associated with this user profile; preserve server-returned values when passing them to another operation.", "type": "string" }, "videoCount": { "description": "Number of video records represented by this user profile.", "type": "integer" } }, "type": "object" }, "Version": { "description": "Structured versions item details for this versions.", "example": { "aboutThisVersion": "Initial release.", "activationTags": [ "tag1", "tag2" ], "baseModel": "SD 1.5", "downloadCount": 10, "externalDownloadUrl": null, "fileName": "model_v1.safetensors", "filePath": "uploads/models/example/model_v1.safetensors", "fileScanEngineVersion": "clamscan --no-summary", "fileScanMeta": { "scanner": "clamav" }, "fileScanReason": null, "fileScanSource": "local_upload", "fileScanStatus": "CLEAN", "fileScannedAt": "2026-03-19T10:00:00.000Z", "fileSizeKb": 131072, "id": 1, "imageOrder": [ 3, 1, 2 ], "images": [], "originalName": "model_v1.safetensors", "publishAt": null, "sha256": "abcdef123456...", "sha256webui": "1234abcd", "status": "PUBLISHED", "supporterEarlyAccessEnabled": true, "trainingMetadataSummary": { "dataset": { "dirs": [ { "imageCount": 128, "name": "cats" } ], "totalImages": 256 }, "extractedAt": "2026-02-19T10:00:00.000Z", "run": { "epoch": 3, "learningRate": 0.0001, "optimizer": "AdamW8bit", "resolution": "1024x1024", "totalEpochs": 10 }, "schemaVersion": 1, "source": "upload_local", "tagsTop": [ { "count": 42, "tag": "cat" } ] }, "versionName": "v1" }, "properties": { "aboutThisVersion": { "description": "About This Version associated with this versions item; preserve server-returned values when passing them to another operation.", "type": "string" }, "activationTags": { "description": "Ordered activation tags entries included with this versions item; an empty list means none are available.", "items": { "description": "Activation Tags item associated with this activation tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "baseModel": { "description": "Base Model associated with this versions item; preserve server-returned values when passing them to another operation.", "type": "string" }, "downloadCount": { "description": "Number of download records represented by this versions item.", "type": "integer" }, "earlyAccess": { "$ref": "#/components/schemas/VersionEarlyAccess" }, "externalDownloadUrl": { "description": "Direct external source URL for versions not hosted by Arc en Ciel. It is null for future scheduled versions unless the viewer owns the model or is staff.", "nullable": true, "type": "string" }, "fileName": { "description": "Human-readable file name for this versions item; it is not a stable identifier.", "nullable": true, "type": "string" }, "filePath": { "description": "Server-provided path for the file path associated with this versions item; treat it as opaque.", "nullable": true, "type": "string" }, "fileScanEngineVersion": { "description": "File Scan Engine Version associated with this versions item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "fileScanMeta": { "description": "Structured file scan meta details for this versions item.", "nullable": true, "type": "object" }, "fileScanReason": { "description": "File Scan Reason associated with this versions item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "fileScanSource": { "description": "File Scan Source associated with this versions item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "fileScanStatus": { "description": "Current lifecycle state of this versions item; clients should tolerate future values. Supported values: `UNSCANNED`, `PENDING`, `CLEAN`, `POTENTIALLY_RISKY`, `INFECTED`, `SCAN_ERROR`, `UNVERIFIED_EXTERNAL`.", "enum": [ "UNSCANNED", "PENDING", "CLEAN", "POTENTIALLY_RISKY", "INFECTED", "SCAN_ERROR", "UNVERIFIED_EXTERNAL" ], "type": "string" }, "fileScannedAt": { "description": "UTC timestamp for the file scanned at transition of this versions item. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "fileSizeKb": { "description": "Size of the associated versions item content in the unit indicated by the field name.", "nullable": true, "type": "integer" }, "id": { "description": "Stable identifier for the versions item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "imageOrder": { "description": "Ordered image order entries included with this versions item; an empty list means none are available.", "items": { "description": "Numeric image order item reported for this image order.", "type": "integer" }, "type": "array" }, "images": { "description": "Ordered images entries included with this versions item; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Image" }, "type": "array" }, "originalName": { "description": "Human-readable original name for this versions item; it is not a stable identifier.", "nullable": true, "type": "string" }, "publishAt": { "description": "UTC publication time for this versions item; a future value indicates scheduled publication. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "sha256": { "description": "Full SHA-256 hash for byte verification.", "nullable": true, "type": "string" }, "sha256webui": { "description": "Stable Diffusion WebUI compatibility hash; do not use as a substitute for full SHA-256 verification.", "nullable": true, "type": "string" }, "status": { "description": "Current lifecycle state of this versions item; clients should tolerate future values.", "type": "string" }, "supporterEarlyAccessEnabled": { "default": true, "description": "Creator-controlled opt-out. External versions remain ineligible regardless of this value.", "type": "boolean" }, "trainingMetadataSummary": { "description": "Structured training metadata summary details for this versions item.", "nullable": true, "properties": { "dataset": { "description": "Structured dataset details for this training metadata summary.", "properties": { "dirs": { "description": "Ordered dirs entries included with this dataset; an empty list means none are available.", "items": { "description": "Structured dirs item details for this dirs.", "properties": { "imageCount": { "description": "Number of image records represented by this dirs item.", "type": "integer" }, "name": { "description": "Human-readable name for this dirs item; it is not a stable identifier.", "type": "string" } }, "type": "object" }, "type": "array" }, "totalImages": { "description": "Numeric total images reported for this dataset.", "type": "integer" } }, "type": "object" }, "extractedAt": { "description": "UTC timestamp for the extracted at transition of this training metadata summary. Format: date-time.", "format": "date-time", "type": "string" }, "run": { "description": "Structured run details for this training metadata summary.", "properties": { "batchSize": { "description": "Numeric batch size reported for this run.", "type": "integer" }, "epoch": { "description": "Numeric epoch reported for this run.", "type": "integer" }, "learningRate": { "description": "Numeric learning rate reported for this run.", "type": "number" }, "optimizer": { "description": "Optimizer associated with this run; preserve server-returned values when passing them to another operation.", "type": "string" }, "resolution": { "description": "Resolution associated with this run; preserve server-returned values when passing them to another operation.", "type": "string" }, "scheduler": { "description": "Scheduler associated with this run; preserve server-returned values when passing them to another operation.", "type": "string" }, "steps": { "description": "Numeric steps reported for this run.", "type": "integer" }, "textEncoderLearningRate": { "description": "Numeric text encoder learning rate reported for this run.", "type": "number" }, "totalEpochs": { "description": "Numeric total epochs reported for this run.", "type": "integer" }, "unetLearningRate": { "description": "Numeric unet learning rate reported for this run.", "type": "number" } }, "type": "object" }, "schemaVersion": { "description": "Numeric schema version reported for this training metadata summary. Supported values: `1`.", "enum": [ 1 ], "type": "integer" }, "source": { "description": "Source associated with this training metadata summary; preserve server-returned values when passing them to another operation. Supported values: `upload_local`, `upload_hf`, `admin_backfill`.", "enum": [ "upload_local", "upload_hf", "admin_backfill" ], "type": "string" }, "tagsTop": { "description": "Ordered tags top entries included with this training metadata summary; an empty list means none are available.", "items": { "description": "Structured tags top item details for this tags top.", "properties": { "count": { "description": "Number of count records represented by this tags top item.", "type": "integer" }, "tag": { "description": "Tag associated with this tags top item; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "versionName": { "description": "Human-readable version name for this versions item; it is not a stable identifier.", "type": "string" } }, "type": "object" }, "VersionDownloadInfo": { "description": "Stable JSON contract for third-party model download clients.", "example": { "allowedRedirectHosts": [ "uploads.arcenciel.io" ], "available": true, "blocked": false, "downloadUrl": "/api/models/1/versions/2/download/model_v1.safetensors", "earlyAccess": { "canDownload": false, "canDownloadViaLink": false, "enabled": false, "reason": "PUBLIC", "startsAt": null, "state": "PUBLIC", "windowHours": 72 }, "externalDownloadUrl": null, "fileName": "model_v1.safetensors", "fileScanReason": null, "fileScanStatus": "CLEAN", "fileSizeKb": 131072, "modelId": 1, "originalName": "model_v1.safetensors", "registerUrl": "/api/models/1/versions/2/download/register", "sha256": "abcdef123456...", "sha256webui": "1234abcd", "source": "hosted", "status": "PUBLISHED", "versionId": 2 }, "properties": { "allowedRedirectHosts": { "description": "Additional HTTPS hosts a client should allow when following the canonical Arc download URL.", "items": { "description": "Allowed Redirect Hosts item associated with this allowed redirect hosts; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "available": { "description": "True when the version has a usable download source and is not scan-blocked.", "type": "boolean" }, "blocked": { "description": "True when file safety status prevents direct download delivery.", "type": "boolean" }, "downloadUrl": { "description": "Canonical Arc download URL for hosted files. Start here and allow documented redirects.", "nullable": true, "type": "string" }, "earlyAccess": { "$ref": "#/components/schemas/VersionEarlyAccess" }, "externalDownloadUrl": { "description": "External source URL for external-only versions. Null for hosted files and scan-blocked entries.", "nullable": true, "type": "string" }, "fileName": { "description": "Safe filename clients can use for local storage.", "type": "string" }, "fileScanReason": { "description": "File Scan Reason associated with this version download info; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "fileScanStatus": { "description": "Current lifecycle state of this version download info; clients should tolerate future values. Supported values: `UNSCANNED`, `PENDING`, `CLEAN`, `POTENTIALLY_RISKY`, `INFECTED`, `SCAN_ERROR`, `UNVERIFIED_EXTERNAL`.", "enum": [ "UNSCANNED", "PENDING", "CLEAN", "POTENTIALLY_RISKY", "INFECTED", "SCAN_ERROR", "UNVERIFIED_EXTERNAL" ], "type": "string" }, "fileSizeKb": { "description": "Size of the associated version download info content in the unit indicated by the field name.", "nullable": true, "type": "integer" }, "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "type": "integer" }, "originalName": { "description": "Human-readable original name for this version download info; it is not a stable identifier.", "nullable": true, "type": "string" }, "registerUrl": { "description": "Endpoint to record a completed direct or external download without streaming through Arc.", "nullable": true, "type": "string" }, "sha256": { "description": "Full SHA-256 hash for byte verification.", "nullable": true, "type": "string" }, "sha256webui": { "description": "Stable Diffusion WebUI compatibility hash.", "nullable": true, "type": "string" }, "source": { "description": "Hosted files are served by Arc en Ciel; external files must be fetched from externalDownloadUrl by clients that support them.", "enum": [ "hosted", "external" ], "nullable": true, "type": "string" }, "status": { "description": "Current lifecycle state of this version download info; clients should tolerate future values.", "type": "string" }, "versionId": { "description": "Stable identifier for the version; use it in subsequent API calls instead of a display name.", "type": "integer" } }, "type": "object" }, "VersionEarlyAccess": { "description": "Structured early access details for this versions item.", "properties": { "canDownload": { "description": "Whether can download applies to this early access.", "type": "boolean" }, "canDownloadViaLink": { "description": "Whether can download via link applies to this early access.", "type": "boolean" }, "enabled": { "description": "True when the version is configured and eligible for the supporter early-access flow.", "type": "boolean" }, "reason": { "description": "Stable machine-readable reason for the current state.", "type": "string" }, "startsAt": { "description": "UTC timestamp for the starts at transition of this early access. Format: date-time.", "format": "date-time", "nullable": true, "type": "string" }, "state": { "description": "Current lifecycle state of this early access; clients should tolerate future values. Supported values: `PUBLIC`, `AVAILABLE`, `UPCOMING`, `LOCKED`, `DISABLED`, `UNAVAILABLE`.", "enum": [ "PUBLIC", "AVAILABLE", "UPCOMING", "LOCKED", "DISABLED", "UNAVAILABLE" ], "type": "string" }, "windowHours": { "description": "Numeric window hours reported for this early access.", "example": 72, "type": "integer" } }, "required": [ "enabled", "windowHours", "startsAt", "state", "canDownload", "canDownloadViaLink", "reason" ], "type": "object" }, "Video": { "description": "Fields describing video in Developer API requests and responses.", "example": { "createdAt": "2025-01-01T12:00:00Z", "description": "A sample video description.", "dislike": 2, "filePath": "videos/sample.mp4", "heart": 5, "id": "abc123", "like": 10, "streamManifestPath": "videos/sample_hls/index.m3u8", "tags": [ "demo", "sample" ], "title": "Sample Video", "updatedAt": "2025-01-02T09:00:00Z", "uploader": { "id": 1, "username": "john_doe" } }, "properties": { "createdAt": { "description": "UTC timestamp when this video was created. Format: date-time.", "format": "date-time", "type": "string" }, "description": { "description": "User-facing description of this video; it may contain an empty string when no description was supplied.", "type": "string" }, "dislike": { "description": "Numeric dislike reported for this video.", "type": "number" }, "filePath": { "description": "Server-provided path for the file path associated with this video; treat it as opaque.", "type": "string" }, "heart": { "description": "Numeric heart reported for this video.", "type": "number" }, "id": { "description": "Stable identifier for the video; use it in subsequent API calls instead of a display name.", "type": "string" }, "like": { "description": "Numeric like reported for this video.", "type": "number" }, "streamManifestPath": { "description": "Server-provided path for the stream manifest path associated with this video; treat it as opaque.", "nullable": true, "type": "string" }, "tags": { "description": "Ordered tags entries included with this video; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "title": { "description": "Display title shown to users for this video.", "type": "string" }, "updatedAt": { "description": "UTC timestamp of the most recent persisted change to this video. Format: date-time.", "format": "date-time", "type": "string" }, "uploader": { "$ref": "#/components/schemas/User" } }, "type": "object" } }, "securitySchemes": { "apiKeyAuth": { "in": "header", "name": "x-api-key", "type": "apiKey" }, "bearerAuth": { "bearerFormat": "JWT", "scheme": "bearer", "type": "http" }, "sessionCookieAuth": { "description": "Browser session cookie issued by Arc en Ciel authentication endpoints.", "in": "cookie", "name": "token", "type": "apiKey" } }, "x-api-key-scopes": [ { "description": "No API-key scope is required.", "name": "None", "value": 0 }, { "description": "Read current-user and user profile data.", "name": "ProfileRead", "value": 1 }, { "description": "Update current-user profile data and settings.", "name": "ProfileWrite", "value": 2 }, { "description": "Read models, versions, files, downloads, and model metadata.", "name": "ModelsRead", "value": 4 }, { "description": "Create or update models, versions, and model upload sessions.", "name": "ModelsWrite", "value": 8 }, { "description": "Delete models or model versions.", "name": "ModelsDelete", "value": 16 }, { "description": "Read images, image metadata, related images, and image downloads.", "name": "ImagesRead", "value": 32 }, { "description": "Upload, update, publish, schedule, pin, or crosspost images.", "name": "ImagesWrite", "value": 64 }, { "description": "Delete images.", "name": "ImagesDelete", "value": 128 }, { "description": "Read videos, video metadata, streams, related videos, and downloads.", "name": "VideosRead", "value": 256 }, { "description": "Upload, update, publish, schedule, or showcase videos.", "name": "VideosWrite", "value": 512 }, { "description": "Delete videos.", "name": "VideosDelete", "value": 1024 }, { "description": "Read articles and article metadata.", "name": "ArticlesRead", "value": 2048 }, { "description": "Create, update, publish, schedule, or showcase articles.", "name": "ArticlesWrite", "value": 4096 }, { "description": "Delete articles.", "name": "ArticlesDelete", "value": 8192 }, { "description": "Read collections and collaboration pages.", "name": "CollectionsRead", "value": 16384 }, { "description": "Create or update collections and collaboration participation.", "name": "CollectionsWrite", "value": 32768 }, { "description": "Read generator catalog, presets, jobs, outputs, and events.", "name": "GeneratorRead", "value": 65536 }, { "description": "Create or mutate generator jobs, uploads, presets, and outputs.", "name": "GeneratorWrite", "value": 131072 }, { "description": "Read notification lists and summaries.", "name": "NotificationsRead", "value": 262144 }, { "description": "Manage notification read state.", "name": "NotificationsWrite", "value": 524288 }, { "description": "Write comments, reactions, reports, favorites, and follows.", "name": "SocialWrite", "value": 1048576 }, { "description": "Read feedback and illegal-content notice records visible to the user.", "name": "FeedbackRead", "value": 2097152 }, { "description": "Create or update feedback and illegal-content notice records.", "name": "FeedbackWrite", "value": 4194304 }, { "description": "Read chat threads, messages, presence, unread counts, and link previews.", "name": "ChatRead", "value": 8388608 }, { "description": "Create or update chat messages, groups, requests, reactions, and state.", "name": "ChatWrite", "value": 16777216 }, { "description": "Read owned webhook endpoints and delivery history.", "name": "WebhooksRead", "value": 33554432 }, { "description": "Create and manage owned webhook endpoints and retries.", "name": "WebhooksWrite", "value": 67108864 } ] }, "externalDocs": { "description": "Developer portal, quickstarts, lifecycle policy, SDK status, and support paths.", "url": "https://arcenciel.io/developers" }, "info": { "contact": { "name": "Arc en Ciel Developer Support", "url": "https://arcenciel.io/developers#support" }, "description": "Stable, SDK-oriented Arc en Ciel API v1 contract for catalogue discovery, personal and social workflows, creator publishing, generation, private chat, feedback, privacy-filtered trust and safety cases, managed media, collections, and safe binary transfers. The complete public API reference contains additional evolving operations outside this compatibility profile.\n\nRuntime resource URLs deliberately remain under `/api/...`; v1 is versioned by this immutable contract rather than a `/api/v1/...` path prefix. Additive releases preserve existing v1 requests and responses, while a future breaking v2 will use a parallel migration surface and the published deprecation policy.", "termsOfService": "https://arcenciel.io/terms-of-service", "title": "Arc en Ciel Developer API", "version": "1.9.2" }, "openapi": "3.0.0", "paths": { "/api/articles": { "post": { "description": "Create an article draft with sanitized content, tags, optional thumbnail media, visibility metadata, and caller ownership. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "createArticle", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "content": "example", "tags": "example", "thumbnailFile": "example", "title": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "content": { "description": "Sanitized rich HTML article body. Legacy Markdown or mixed Markdown/HTML is accepted for compatibility and rendered by the rich-content pipeline.", "type": "string" }, "tags": { "description": "Tags associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "thumbnailFile": { "description": "Thumbnail File associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "article": { "content": "

Example section

This is the content of the article.

", "createdAt": "2025-01-01T12:00:00Z", "id": 1, "tags": [ "ai", "stable diffusion" ], "thumbnailFile": "uploads/articles/example.png", "title": "Example Article", "updatedAt": "2025-01-01T12:00:00Z" }, "message": "Article created" }, "schema": { "$ref": "#/components/schemas/DeveloperArticleMutationResponse" } } }, "description": "Article successfully created.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } }, "operationConflict": { "summary": "Operation-specific error", "value": { "error": "The request conflicts with the current resource state.", "errorCode": "CONFLICT", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The request conflicts with the current state of the target resource. The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a new article", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesWrite", "x-api-key-required-scope-mask": 4096, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/articles' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/articles',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/articles/images/{imageId}": { "get": { "description": "Transfer an article image in an available web image format after applying article visibility rules. Clients should use the returned Content-Type instead of inferring a format from the URL.", "operationId": "getArticleImage", "parameters": [ { "description": "Image Id provided in the path.", "example": 1, "in": "path", "name": "imageId", "required": true, "schema": { "description": "Image Id value documented for this operation.", "type": "integer" } }, { "description": "Optional generated image variant name.", "example": "example-variant", "in": "query", "name": "variant", "required": false, "schema": { "description": "Variant value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "description": "200 response for api articles images image Id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/png": { "schema": { "description": "200 response for api articles images image Id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/webp": { "schema": { "description": "200 response for api articles images image Id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Article image file.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid image id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or not visible to the viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve an article image", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesRead", "x-api-key-required-scope-mask": 2048, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/articles/images/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/images/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/articles/images/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/articles/search": { "get": { "description": "Search visible articles with pagination and filters. Anonymous callers receive public articles; authenticated owners and staff may receive additional content allowed by the runtime visibility policy.", "operationId": "searchArticles", "parameters": [ { "description": "Search query applied to title, content, and tags (supports", "example": "landscape", "in": "query", "name": "search", "schema": { "description": "Search value documented for this operation.", "type": "string" } }, { "description": "Sort order for articles (newest uses bumpedAt; manual content edits bump at most once per 24h; autosave excluded. hot = recent articles sorted by favorites).", "example": "newest", "in": "query", "name": "sort", "schema": { "description": "Sort value documented for this operation. Supported values: `newest`, `oldest`, `favorites`, `hot`.", "enum": [ "newest", "oldest", "favorites", "hot" ], "type": "string" } }, { "description": "Page number.", "example": 1, "in": "query", "name": "page", "schema": { "default": 1, "description": "Page value documented for this operation.", "type": "integer" } }, { "description": "Number of articles per page (max 1000).", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "description": "Limit value documented for this operation.", "type": "integer" } }, { "description": "Filter articles by uploader id.", "example": 1, "in": "query", "name": "userId", "schema": { "description": "User Id value documented for this operation.", "type": "integer" } }, { "description": "Auth only. Return articles favorited by the current user.", "example": true, "in": "query", "name": "selfFavorited", "schema": { "description": "Self Favorited value documented for this operation.", "type": "boolean" } }, { "description": "Auth only. Return articles uploaded by users the current user follows.", "example": true, "in": "query", "name": "selfFollowing", "schema": { "description": "Self Following value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "content": "

Example section

This is the content of the article.

", "createdAt": "2025-01-01T12:00:00Z", "id": 1, "tags": [ "ai", "stable diffusion" ], "thumbnailFile": "uploads/articles/example.png", "title": "Example Article", "updatedAt": "2025-01-01T12:00:00Z" } ], "limit": 1, "page": 1, "showcased": [ { "content": "

Example section

This is the content of the article.

", "createdAt": "2025-01-01T12:00:00Z", "id": 1, "tags": [ "ai", "stable diffusion" ], "thumbnailFile": "uploads/articles/example.png", "title": "Example Article", "updatedAt": "2025-01-01T12:00:00Z" } ], "totalCount": 1, "totalPages": 1 }, "schema": { "description": "Fields describing 200 response for api articles search in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api articles search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Article" }, "type": "array" }, "limit": { "description": "Maximum number of records requested or returned in one page of this 200 response for api articles search.", "type": "integer" }, "page": { "description": "One-based result page requested or returned for this 200 response for api articles search.", "type": "integer" }, "showcased": { "description": "Ordered showcased entries included with this 200 response for api articles search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Article" }, "type": "array" }, "totalCount": { "description": "Total number of matching records across all pages for this 200 response for api articles search.", "type": "integer" }, "totalPages": { "description": "Total number of pages available at the current page size for this 200 response for api articles search.", "type": "integer" } }, "type": "object" } } }, "description": "A paginated list of articles.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search articles", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesRead", "x-api-key-required-scope-mask": 2048, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/articles/search' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/search', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/articles/search',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "content-search", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/articles/{articleId}/comments": { "get": { "description": "List comments visible on one article. This read accepts anonymous callers, while an ArticlesRead API key may be used for consistent attribution and support diagnostics.", "operationId": "listArticleComments", "parameters": [ { "description": "The ID of the article.", "example": 1, "in": "path", "name": "articleId", "required": true, "schema": { "description": "Article Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" } ], "schema": { "items": { "$ref": "#/components/schemas/DeveloperComment" }, "type": "array" } } }, "description": "Returns an array of comments.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List all comments for a specific article", "tags": [ "Comments" ], "x-api-key-required-scope": "ArticlesRead", "x-api-key-required-scope-mask": 2048, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/articles/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/comments', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/articles/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a comment on a visible article. Supply an Idempotency-Key when a request may be retried so network failures cannot create duplicate comments.", "operationId": "createArticleComment", "parameters": [ { "description": "The ID of the article to comment on.", "example": 1, "in": "path", "name": "articleId", "required": true, "schema": { "description": "Article Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" }, "parentComment": { "example": null, "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "content" ], "type": "object" } } }, "description": "Comment text and optional parent comment.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment created" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment created successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a comment on an article", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/articles/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/comments', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/articles/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "social-comment-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/articles/{articleId}/comments/{commentId}": { "delete": { "description": "Delete a caller-owned comment from an article. The article identifier is validated with the comment so a record cannot be deleted through another target.", "operationId": "deleteArticleComment", "parameters": [ { "description": "Article Id provided in the path.", "example": 1, "in": "path", "name": "articleId", "required": true, "schema": { "description": "Article Id value documented for this operation.", "type": "integer" } }, { "description": "Comment Id provided in the path.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Comment deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a comment on an article", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/articles/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/comments/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/articles/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Replace the editable content of the caller-owned article comment. Ownership is enforced by the runtime and other users cannot update the record.", "operationId": "updateArticleComment", "parameters": [ { "description": "Article Id provided in the path.", "example": 1, "in": "path", "name": "articleId", "required": true, "schema": { "description": "Article Id value documented for this operation.", "type": "integer" } }, { "description": "Comment Id provided in the path.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" } } }, "description": "Replacement comment text.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment updated" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update an existing comment on an article", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/articles/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/comments/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/articles/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/articles/{id}": { "delete": { "description": "Soft-delete a caller-managed article and remove its content from normal visibility without reusing its identifier. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "deleteArticle", "parameters": [ { "description": "The unique ID of the article to delete.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Article deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Soft-delete an article", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesDelete", "x-api-key-required-scope-mask": 8192, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/articles/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/articles/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one article visible to the caller, including its public author and media metadata. Draft and scheduled visibility continues to follow owner, staff, and publication-time rules.", "operationId": "getArticle", "parameters": [ { "description": "The unique ID of the article.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "content": "

Example section

This is the content of the article.

", "createdAt": "2025-01-01T12:00:00Z", "id": 1, "tags": [ "ai", "stable diffusion" ], "thumbnailFile": "uploads/articles/example.png", "title": "Example Article", "updatedAt": "2025-01-01T12:00:00Z" }, "schema": { "$ref": "#/components/schemas/Article" } } }, "description": "The requested article.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve an article by its ID", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesRead", "x-api-key-required-scope-mask": 2048, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/articles/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/articles/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update supported article fields and optionally replace its thumbnail while preserving ownership and publication visibility rules. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateArticle", "parameters": [ { "description": "The unique ID of the article to update.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "value", "tags": "value", "title": "value" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "content": { "description": "Sanitized rich HTML article body. Legacy Markdown or mixed Markdown/HTML is accepted for compatibility and rendered by the rich-content pipeline.", "type": "string" }, "tags": { "description": "Tags associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "article": { "content": "

Example section

This is the content of the article.

", "createdAt": "2025-01-01T12:00:00Z", "id": 1, "tags": [ "ai", "stable diffusion" ], "thumbnailFile": "uploads/articles/example.png", "title": "Example Article", "updatedAt": "2025-01-01T12:00:00Z" }, "message": "Article updated" }, "schema": { "$ref": "#/components/schemas/DeveloperArticleMutationResponse" } } }, "description": "Article updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden – insufficient permissions.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update an existing article", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesWrite", "x-api-key-required-scope-mask": 4096, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/articles/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"title\":\"value\",\"content\":\"value\",\"tags\":\"value\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"title\": \"value\",\n \"content\": \"value\",\n \"tags\": \"value\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/articles/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"title\\\":\\\"value\\\",\\\"content\\\":\\\"value\\\",\\\"tags\\\":\\\"value\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/articles/{id}/favorited": { "patch": { "description": "Set the current caller’s favorite state for a visible article using an explicit boolean. Repeating the same desired state cannot reverse the result.", "operationId": "setArticleFavorite", "parameters": [ { "description": "The article ID.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "favorite": true }, "schema": { "properties": { "favorite": { "description": "The desired favorite state.", "example": true, "type": "boolean" } }, "required": [ "favorite" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Favorite state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Favorite or unfavorite an article", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/articles/123/favorited' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"favorite\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/favorited', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"favorite\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/articles/123/favorited',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"favorite\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "social-favorite", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/articles/{id}/images": { "post": { "description": "Upload validated inline images to an article owned by the caller and report partial validation failures without hiding accepted media. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadArticleImages", "parameters": [ { "description": "The article ID.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "imageFiles": [ "example" ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "imageFiles": { "description": "Ordered image files entries included with this request payload; an empty list means none are available.", "items": { "description": "Image Files item associated with this image files; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "images": [ { "filePath": "uploads/images/108.webp", "id": 108 } ] }, "schema": { "$ref": "#/components/schemas/DeveloperStoredImagesUploadResponse" } } }, "description": "Images uploaded.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "images": [ { "filePath": "uploads/images/108.webp", "id": 108 } ] }, "schema": { "$ref": "#/components/schemas/DeveloperStoredImagesUploadResponse" } } }, "description": "Some images were rejected while the remaining images were stored.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "The caller may not edit this article.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload images for an article", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesWrite", "x-api-key-required-scope-mask": 4096, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/articles/123/images' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/images', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/articles/123/images',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/articles/{id}/publish": { "post": { "description": "Publish a caller-managed article draft immediately after enforcing publication status, ownership, and content lifecycle rules. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "publishArticle", "parameters": [ { "description": "The article ID.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Article published.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Publish an article", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesWrite", "x-api-key-required-scope-mask": 4096, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/articles/123/publish' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/publish', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/articles/123/publish',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/articles/{id}/showcased": { "patch": { "description": "Set the explicit showcased state for a caller-owned article while enforcing the per-profile showcase limit. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "setArticleShowcase", "parameters": [ { "description": "The article ID.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Showcase state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Article not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Showcase or unshowcase an article", "tags": [ "Articles" ], "x-api-key-required-scope": "ArticlesWrite", "x-api-key-required-scope-mask": 4096, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/articles/123/showcased' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/articles/123/showcased', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/articles/123/showcased',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/chat/groups": { "post": { "description": "Create a group conversation owned by an eligible creator or staff caller and invite a deduplicated set of existing users. Idempotency prevents duplicate groups on retry.", "operationId": "createChatGroup", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "title": "Release artwork", "userIds": [ 18, 27 ] }, "schema": { "properties": { "title": { "description": "Optional group display title.", "maxLength": 80, "nullable": true, "type": "string" }, "userIds": { "description": "Existing users to invite as pending members.", "items": { "minimum": 1, "type": "integer" }, "type": "array", "uniqueItems": true } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T10:00:00.000Z", "createdById": 42, "directRequesterId": null, "directStatus": null, "hasUnread": true, "id": 81, "imagePath": "/uploads/chat/group-81.webp?token=temporary", "kind": "GROUP", "lastMessage": { "attachments": [ { "bytes": 182430, "createdAt": "2026-08-07T10:00:00.000Z", "durationMs": null, "filePath": "/uploads/chat/thread-81/image.webp?token=temporary", "height": 1024, "id": 901, "kind": "IMAGE", "mimeType": "image/webp", "width": 1024 } ], "content": "The new render is ready.", "createdAt": "2026-08-07T10:00:00.000Z", "id": 501, "senderId": 42 }, "lastMessageAt": "2026-08-07T10:00:00.000Z", "participants": [ { "archivedAt": null, "role": "MEMBER", "state": "ACTIVE", "user": { "badges": [ { "icon": "ri-brush-line", "id": 7, "name": "Creator", "type": "CREATOR" } ], "id": 42, "namecardPreference": "aurora", "profilePicture": "/uploads/profile/42.webp", "profilePictureRating": "SAFE", "role": "CREATOR", "username": "aurora" }, "userId": 18 } ], "title": "Release artwork", "updatedAt": "2026-08-07T10:00:00.000Z", "viewer": { "archivedAt": null, "lastReadAt": "2026-08-07T10:00:00.000Z", "lastReadMessageId": 498, "role": "MEMBER", "state": "ACTIVE" } }, "schema": { "$ref": "#/components/schemas/DeveloperChatThread" } } }, "description": "Group thread created.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a group thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/groups' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"title\":\"Release artwork\",\"userIds\":[18,27]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/groups', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"title\": \"Release artwork\",\n \"userIds\": [\n 18,\n 27\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/groups',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"title\\\":\\\"Release artwork\\\",\\\"userIds\\\":[18,27]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/chat/link-preview": { "get": { "description": "Resolve a visibility-checked Arc en Ciel resource or guarded external URL into a compact preview suitable for composing a chat message without exposing private content.", "operationId": "getChatLinkPreview", "parameters": [ { "description": "Absolute HTTP(S) URL to preview. Internal resources remain subject to caller visibility checks.", "example": "https://arcenciel.io/images/108", "in": "query", "name": "url", "required": true, "schema": { "format": "uri", "maxLength": 2000, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "kind": "IMAGE", "url": "https://arcenciel.io/images/108" }, "schema": { "$ref": "#/components/schemas/DeveloperChatLinkPreview" } } }, "description": "Preview resolved.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing or invalid URL.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Resolve a link preview for a URL", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatRead", "x-api-key-required-scope-mask": 8388608, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/chat/link-preview' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/link-preview', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/chat/link-preview',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/chat/messages/{messageId}/reactions": { "post": { "description": "Toggle the authenticated caller’s validated emote reaction on an accessible message and return the complete caller-relative reaction summary. This toggle is not retry-safe.", "operationId": "toggleChatMessageReaction", "parameters": [ { "description": "Message Id provided in the path.", "example": 81, "in": "path", "name": "messageId", "required": true, "schema": { "description": "Message Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "emoteName": "heart" }, "schema": { "properties": { "emoteName": { "description": "Existing public emote name whose caller reaction is toggled.", "pattern": "^[a-z0-9_]{1,32}$", "type": "string" } }, "required": [ "emoteName" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "messageId": 501, "reactions": [ { "count": 2, "emoteName": "heart", "users": [ { "badges": [ { "icon": "ri-brush-line", "id": 7, "name": "Creator", "type": "CREATOR" } ], "id": 42, "namecardPreference": "aurora", "profilePicture": "/uploads/profile/42.webp", "profilePictureRating": "SAFE", "role": "CREATOR", "username": "aurora" } ] } ] }, "schema": { "$ref": "#/components/schemas/DeveloperChatReactionResponse" } } }, "description": "Reaction state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Message not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Toggle a reaction for a message", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/messages/123/reactions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"emoteName\":\"heart\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/messages/123/reactions', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"emoteName\": \"heart\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/messages/123/reactions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"emoteName\\\":\\\"heart\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/chat/presence": { "get": { "description": "Return a bounded presence snapshot for explicitly requested user identifiers. Presence is caller-authenticated and clients must treat timestamps and online state as transient hints.", "operationId": "getChatPresence", "parameters": [ { "description": "One to 200 decimal user identifiers, encoded as a comma-separated list.", "example": [ 18, 42 ], "explode": false, "in": "query", "name": "userIds", "required": true, "schema": { "items": { "minimum": 1, "type": "integer" }, "maxItems": 200, "minItems": 1, "type": "array", "uniqueItems": true }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "42": { "lastSeenAt": "2026-08-07T10:00:00.000Z", "online": true } } }, "schema": { "$ref": "#/components/schemas/DeveloperChatPresenceResponse" } } }, "description": "Presence payload returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get presence information for chat contacts", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatRead", "x-api-key-required-scope-mask": 8388608, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/chat/presence' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/presence', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/chat/presence',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/chat/requests": { "post": { "description": "Open or reuse a direct conversation with another available user and optionally send its first text and validated attachments. Idempotency prevents duplicate requests or messages on retry.", "operationId": "createChatRequest", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "attachments": [ "" ], "content": "Would you like to collaborate?", "toUserId": 18 }, "schema": { "properties": { "attachments": { "description": "Optional validated image, GIF, or video files for the initial message.", "items": { "format": "binary", "type": "string" }, "maxItems": 10, "type": "array" }, "content": { "description": "Optional initial direct-message text.", "minLength": 1, "type": "string" }, "toUserId": { "description": "Recipient user identifier.", "minimum": 1, "type": "integer" } }, "required": [ "toUserId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "threadId": 81 }, "schema": { "$ref": "#/components/schemas/DeveloperChatRequestResponse" } } }, "description": "Existing direct thread or repeated request returned.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "201": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T10:00:00.000Z", "createdById": 42, "directRequesterId": null, "directStatus": null, "hasUnread": true, "id": 81, "imagePath": "/uploads/chat/group-81.webp?token=temporary", "kind": "GROUP", "lastMessage": { "attachments": [ { "bytes": 182430, "createdAt": "2026-08-07T10:00:00.000Z", "durationMs": null, "filePath": "/uploads/chat/thread-81/image.webp?token=temporary", "height": 1024, "id": 901, "kind": "IMAGE", "mimeType": "image/webp", "width": 1024 } ], "content": "The new render is ready.", "createdAt": "2026-08-07T10:00:00.000Z", "id": 501, "senderId": 42 }, "lastMessageAt": "2026-08-07T10:00:00.000Z", "participants": [ { "archivedAt": null, "role": "MEMBER", "state": "ACTIVE", "user": { "badges": [ { "icon": "ri-brush-line", "id": 7, "name": "Creator", "type": "CREATOR" } ], "id": 42, "namecardPreference": "aurora", "profilePicture": "/uploads/profile/42.webp", "profilePictureRating": "SAFE", "role": "CREATOR", "username": "aurora" }, "userId": 18 } ], "title": "Release artwork", "updatedAt": "2026-08-07T10:00:00.000Z", "viewer": { "archivedAt": null, "lastReadAt": "2026-08-07T10:00:00.000Z", "lastReadMessageId": 498, "role": "MEMBER", "state": "ACTIVE" } }, "schema": { "$ref": "#/components/schemas/DeveloperChatThread" } } }, "description": "New direct request created.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a direct chat request", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/requests' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/requests', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/requests',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/chat/threads": { "get": { "description": "List the authenticated caller’s visible inbox, incoming requests, outgoing requests, or archived conversations with participant-safe summaries and unread state.", "operationId": "listChatThreads", "parameters": [ { "description": "Caller-relative conversation folder.", "example": "inbox", "in": "query", "name": "folder", "required": false, "schema": { "default": "inbox", "enum": [ "inbox", "requests_in", "requests_out", "archived" ], "type": "string" } }, { "description": "Maximum number of conversations returned.", "example": 30, "in": "query", "name": "limit", "required": false, "schema": { "default": 30, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2026-08-07T10:00:00.000Z", "createdById": 42, "directRequesterId": null, "directStatus": null, "hasUnread": true, "id": 81, "imagePath": "/uploads/chat/group-81.webp?token=temporary", "kind": "GROUP", "lastMessage": { "attachments": [ { "bytes": 182430, "createdAt": "2026-08-07T10:00:00.000Z", "durationMs": null, "filePath": "/uploads/chat/thread-81/image.webp?token=temporary", "height": 1024, "id": 901, "kind": "IMAGE", "mimeType": "image/webp", "width": 1024 } ], "content": "The new render is ready.", "createdAt": "2026-08-07T10:00:00.000Z", "id": 501, "senderId": 42 }, "lastMessageAt": "2026-08-07T10:00:00.000Z", "participants": [ { "archivedAt": null, "role": "MEMBER", "state": "ACTIVE", "user": { "badges": [ { "icon": "ri-brush-line", "id": 7, "name": "Creator", "type": "CREATOR" } ], "id": 42, "namecardPreference": "aurora", "profilePicture": "/uploads/profile/42.webp", "profilePictureRating": "SAFE", "role": "CREATOR", "username": "aurora" }, "userId": 18 } ], "title": "Release artwork", "updatedAt": "2026-08-07T10:00:00.000Z", "viewer": { "archivedAt": null, "lastReadAt": "2026-08-07T10:00:00.000Z", "lastReadMessageId": 498, "role": "MEMBER", "state": "ACTIVE" } } ], "limit": 30 }, "schema": { "$ref": "#/components/schemas/DeveloperChatThreadListResponse" } } }, "description": "Thread list returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List chat threads for the current user", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatRead", "x-api-key-required-scope-mask": 8388608, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/chat/threads' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/chat/threads',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/chat/threads/{threadId}": { "get": { "description": "Return one conversation in which the authenticated caller is an active participant, including caller-relative state, participants, and the latest message summary.", "operationId": "getChatThread", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T10:00:00.000Z", "createdById": 42, "directRequesterId": null, "directStatus": null, "hasUnread": true, "id": 81, "imagePath": "/uploads/chat/group-81.webp?token=temporary", "kind": "GROUP", "lastMessage": { "attachments": [ { "bytes": 182430, "createdAt": "2026-08-07T10:00:00.000Z", "durationMs": null, "filePath": "/uploads/chat/thread-81/image.webp?token=temporary", "height": 1024, "id": 901, "kind": "IMAGE", "mimeType": "image/webp", "width": 1024 } ], "content": "The new render is ready.", "createdAt": "2026-08-07T10:00:00.000Z", "id": 501, "senderId": 42 }, "lastMessageAt": "2026-08-07T10:00:00.000Z", "participants": [ { "archivedAt": null, "role": "MEMBER", "state": "ACTIVE", "user": { "badges": [ { "icon": "ri-brush-line", "id": 7, "name": "Creator", "type": "CREATOR" } ], "id": 42, "namecardPreference": "aurora", "profilePicture": "/uploads/profile/42.webp", "profilePictureRating": "SAFE", "role": "CREATOR", "username": "aurora" }, "userId": 18 } ], "title": "Release artwork", "updatedAt": "2026-08-07T10:00:00.000Z", "viewer": { "archivedAt": null, "lastReadAt": "2026-08-07T10:00:00.000Z", "lastReadMessageId": 498, "role": "MEMBER", "state": "ACTIVE" } }, "schema": { "$ref": "#/components/schemas/DeveloperChatThread" } } }, "description": "Thread found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get a chat thread by id", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatRead", "x-api-key-required-scope-mask": 8388608, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/chat/threads/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/chat/threads/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/chat/threads/{threadId}/accept": { "post": { "description": "Accept an incoming direct-message request or pending group invitation for the authenticated caller after validating its current state and recipient ownership.", "operationId": "acceptChatRequest", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Request accepted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Accept a pending direct request", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/threads/123/accept' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/accept', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/threads/123/accept',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/chat/threads/{threadId}/archive": { "post": { "description": "Archive a caller-accessible conversation for the authenticated caller only. Repeating the operation leaves the conversation archived without affecting other participants.", "operationId": "archiveChatThread", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Thread archived.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Archive a thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/threads/123/archive' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/archive', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/threads/123/archive',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/chat/threads/{threadId}/avatar": { "delete": { "description": "Remove the custom avatar from a group conversation owned by the authenticated caller. Repeating the operation leaves the avatar absent.", "operationId": "removeChatGroupAvatar", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Avatar removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove a group avatar", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/chat/threads/123/avatar' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/avatar', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/chat/threads/123/avatar',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Upload and replace the validated avatar of a group conversation owned by the authenticated caller. Clients must not automatically retry this multipart mutation.", "operationId": "updateChatGroupAvatar", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "avatar": { "description": "Avatar associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" } }, "required": [ "avatar" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "imagePath": "/uploads/chat/group-81.webp?token=temporary" }, "schema": { "$ref": "#/components/schemas/DeveloperChatAvatarResponse" } } }, "description": "Avatar updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid file payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload or replace a group avatar", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/chat/threads/123/avatar' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/avatar', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/chat/threads/123/avatar',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/chat/threads/{threadId}/decline": { "post": { "description": "Decline an incoming direct-message request or pending group invitation for the authenticated caller and archive that caller’s participation state.", "operationId": "declineChatRequest", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Request declined.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Decline a pending direct request", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/threads/123/decline' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/decline', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/threads/123/decline',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/chat/threads/{threadId}/invite": { "post": { "description": "Invite existing users to a caller-owned group conversation. Existing active participants remain active and prior left or declined participants return to pending state.", "operationId": "inviteChatParticipants", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "userIds": [ 27 ] }, "schema": { "properties": { "userIds": { "description": "Existing users to invite or re-invite to the group.", "items": { "minimum": 1, "type": "integer" }, "type": "array", "uniqueItems": true } }, "required": [ "userIds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Participant invited.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Invite a participant to a group thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/threads/123/invite' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"userIds\":[27]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/invite', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"userIds\": [\n 27\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/threads/123/invite',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"userIds\\\":[27]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/chat/threads/{threadId}/leave": { "post": { "description": "Leave a group conversation as a non-owner participant and archive the caller’s membership. Group owners must transfer or close ownership through supported product controls.", "operationId": "leaveChatGroup", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Left thread successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Leave a group thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/threads/123/leave' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/leave', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/threads/123/leave',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/chat/threads/{threadId}/messages": { "get": { "description": "List one caller-accessible conversation’s messages in chronological order using a bounded descending cursor, including signed attachments, replies, mentions, and reaction summaries.", "operationId": "listChatMessages", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } }, { "description": "Return messages with identifiers lower than this cursor.", "example": 500, "in": "query", "name": "cursor", "required": false, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Maximum number of messages returned.", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "attachments": [ { "bytes": 182430, "createdAt": "2026-08-07T10:00:00.000Z", "durationMs": null, "filePath": "/uploads/chat/thread-81/image.webp?token=temporary", "height": 1024, "id": 901, "kind": "IMAGE", "mimeType": "image/webp", "width": 1024 } ], "content": "Here is the finished render, @aurora.", "createdAt": "2026-08-07T10:00:00.000Z", "id": 501, "mentions": { "aurora": 42 }, "reactions": [ { "count": 2, "emoteName": "heart", "users": [ { "badges": [ { "icon": "ri-brush-line", "id": 7, "name": "Creator", "type": "CREATOR" } ], "id": 42, "namecardPreference": "aurora", "profilePicture": "/uploads/profile/42.webp", "profilePictureRating": "SAFE", "role": "CREATOR", "username": "aurora" } ] } ], "replyTo": { "content": "Can you share the final image?", "createdAt": "2026-08-07T10:00:00.000Z", "id": 498, "senderId": 18 }, "senderId": 42, "threadId": 81 } ], "limit": 50, "nextCursor": 450 }, "schema": { "$ref": "#/components/schemas/DeveloperChatMessageListResponse" } } }, "description": "Message list returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List messages for a thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatRead", "x-api-key-required-scope-mask": 8388608, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/chat/threads/123/messages' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/messages', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/chat/threads/123/messages',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a text, attachment, or reply message in a caller-accessible active conversation. Idempotency prevents duplicate messages and attachment records on retry.", "operationId": "createChatMessage", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "attachments": [ "" ], "content": "Here is the finished render.", "replyToMessageId": 498 }, "schema": { "properties": { "attachments": { "description": "Optional validated image, GIF, or video files.", "items": { "format": "binary", "type": "string" }, "maxItems": 10, "type": "array" }, "content": { "description": "Optional message text, including supported @mentions.", "minLength": 1, "type": "string" }, "replyToMessageId": { "description": "Optional message in the same thread to quote and reply to.", "minimum": 1, "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "attachments": [ { "bytes": 182430, "createdAt": "2026-08-07T10:00:00.000Z", "durationMs": null, "filePath": "/uploads/chat/thread-81/image.webp?token=temporary", "height": 1024, "id": 901, "kind": "IMAGE", "mimeType": "image/webp", "width": 1024 } ], "content": "Here is the finished render, @aurora.", "createdAt": "2026-08-07T10:00:00.000Z", "id": 501, "mentions": { "aurora": 42 }, "reactions": [ { "count": 2, "emoteName": "heart", "users": [ { "badges": [ { "icon": "ri-brush-line", "id": 7, "name": "Creator", "type": "CREATOR" } ], "id": 42, "namecardPreference": "aurora", "profilePicture": "/uploads/profile/42.webp", "profilePictureRating": "SAFE", "role": "CREATOR", "username": "aurora" } ] } ], "replyTo": { "content": "Can you share the final image?", "createdAt": "2026-08-07T10:00:00.000Z", "id": 498, "senderId": 18 }, "senderId": 42, "threadId": 81 }, "schema": { "$ref": "#/components/schemas/DeveloperChatMessage" } } }, "description": "Message created.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Post a message to a thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/threads/123/messages' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/messages', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/threads/123/messages',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/chat/threads/{threadId}/participants/{userId}": { "delete": { "description": "Remove a non-owner participant from a group conversation owned by the authenticated caller without exposing or changing unrelated participant state.", "operationId": "removeChatParticipant", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } }, { "description": "User Id provided in the path.", "example": 18, "in": "path", "name": "userId", "required": true, "schema": { "description": "User Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Participant removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread or user not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove a participant from a group thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/chat/threads/123/participants/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/participants/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/chat/threads/123/participants/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/chat/threads/{threadId}/read": { "patch": { "description": "Advance the authenticated caller’s read marker to a supplied message in the conversation or to the latest current message when no identifier is supplied.", "operationId": "markChatThreadRead", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "messageId": 501 }, "schema": { "properties": { "messageId": { "description": "Message in this thread to use as the new read marker; omitted selects the latest message.", "minimum": 1, "nullable": true, "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Read marker updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Mark a thread as read", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/chat/threads/123/read' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"messageId\":501}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/read', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"messageId\": 501\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/chat/threads/123/read',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"messageId\\\":501}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/chat/threads/{threadId}/title": { "patch": { "description": "Replace or clear the display title of a group conversation owned by the authenticated caller while preserving all participant and message state.", "operationId": "updateChatGroupTitle", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "title": "Release artwork" }, "schema": { "properties": { "title": { "description": "New group display title; null or blank clears the custom title.", "maxLength": 80, "nullable": true, "type": "string" } }, "required": [ "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "title": "Release artwork" }, "schema": { "$ref": "#/components/schemas/DeveloperChatTitleResponse" } } }, "description": "Thread title updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update a group thread title", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/chat/threads/123/title' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"title\":\"Release artwork\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/title', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"title\": \"Release artwork\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/chat/threads/123/title',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"title\\\":\\\"Release artwork\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/chat/threads/{threadId}/unarchive": { "post": { "description": "Remove the authenticated caller’s archive marker from an accessible conversation. Repeating the operation leaves it unarchived without changing other participants.", "operationId": "unarchiveChatThread", "parameters": [ { "description": "Thread Id provided in the path.", "example": 81, "in": "path", "name": "threadId", "required": true, "schema": { "description": "Thread Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "$ref": "#/components/schemas/DeveloperChatOkResponse" } } }, "description": "Thread unarchived.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Thread not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Unarchive a thread", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatWrite", "x-api-key-required-scope-mask": 16777216, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/chat/threads/123/unarchive' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/threads/123/unarchive', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/chat/threads/123/unarchive',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/chat/unread-count": { "get": { "description": "Return the authenticated caller’s number of unarchived conversations whose latest message was sent by another participant after the caller’s read marker.", "operationId": "getChatUnreadCount", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "count": 3 }, "schema": { "$ref": "#/components/schemas/DeveloperChatUnreadCountResponse" } } }, "description": "Unread count payload returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get unread chat count", "tags": [ "Chat" ], "x-api-key-required-scope": "ChatRead", "x-api-key-required-scope-mask": 8388608, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/chat/unread-count' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/chat/unread-count', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/chat/unread-count',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/collabs": { "get": { "description": "List public live or historical collaboration events with pagination, availability counts, creator previews, and optional filters. Staff may explicitly request the management view while other callers remain on the public visibility policy.", "operationId": "listCollabs", "parameters": [ { "description": "Page provided in the query.", "example": 1, "in": "query", "name": "page", "schema": { "description": "Page value documented for this operation. Minimum: 1.", "minimum": 1, "type": "integer" } }, { "description": "Limit provided in the query.", "example": 1, "in": "query", "name": "limit", "schema": { "description": "Limit value documented for this operation. Minimum: 1.", "minimum": 1, "type": "integer" } }, { "description": "Search provided in the query.", "example": "landscape", "in": "query", "name": "search", "schema": { "description": "Search value documented for this operation.", "type": "string" } }, { "description": "Staff-only `manage` view; all other callers receive the public view.", "example": "public", "in": "query", "name": "scope", "schema": { "description": "Scope value documented for this operation. Supported values: `public`, `manage`.", "enum": [ "public", "manage" ], "type": "string" } }, { "description": "Filter by the current collaboration status. Unknown values are ignored.", "example": "example-status", "in": "query", "name": "status", "schema": { "description": "Status value documented for this operation.", "type": "string" } }, { "description": "Filter by collaboration category. Unknown values are ignored.", "example": "example-category", "in": "query", "name": "category", "schema": { "description": "Category value documented for this operation.", "type": "string" } }, { "description": "Return collaborations containing the selected accepted participant or historical creator.", "example": 1, "in": "query", "name": "userId", "schema": { "description": "User Id value documented for this operation. Minimum: 1.", "minimum": 1, "type": "integer" } }, { "description": "Select live events or the historical archive. Defaults to `LIVE`.", "example": "LIVE", "in": "query", "name": "mode", "schema": { "description": "Mode value documented for this operation. Supported values: `LIVE`, `HISTORICAL`.", "enum": [ "LIVE", "HISTORICAL" ], "type": "string" } }, { "description": "Optional historical scale filter.", "example": "MAJOR", "in": "query", "name": "scale", "schema": { "description": "Scale value documented for this operation. Supported values: `MAJOR`, `MINI`.", "enum": [ "MAJOR", "MINI" ], "type": "string" } }, { "description": "Optional UTC release year filter.", "example": 1970, "in": "query", "name": "year", "schema": { "description": "Year value documented for this operation. Minimum: 1970. Maximum: 2200.", "maximum": 2200, "minimum": 1970, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2026-07-01T10:00:00.000Z", "id": 7, "mode": "LIVE", "participantCount": 19, "releaseAt": "2026-07-19T16:00:00.000Z", "slug": "geen-n-geener-collab", "status": "RELEASED", "submissionCount": 69, "title": "Geen n Geener Collab", "updatedAt": "2026-07-19T18:00:00.000Z", "visibility": "PUBLIC" } ], "limit": 20, "page": 1, "totalCount": 1, "totalPages": 1 }, "schema": { "$ref": "#/components/schemas/CollabPage" } } }, "description": "Collaboration list returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List collaboration events", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collabs' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collabs',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/collabs/announcement": { "get": { "description": "Return the current public collaboration announcement, or null when no eligible live event is active. Authentication is optional and never expands this announcement response beyond the public summary.", "operationId": "getCollabAnnouncement", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "announcementEnabled": true, "createdAt": "2026-07-25T14:33:00.395Z", "id": 140, "mode": "LIVE", "participantCount": 9, "releaseAt": "2026-08-09T16:00:00.000Z", "slug": "bold-bluenettes-collab", "status": "OPEN", "submissionCount": 52, "title": "Bold Bluenettes Collab", "updatedAt": "2026-07-25T14:36:33.937Z", "visibility": "PUBLIC" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/CollabSummary" } ], "description": "200 response for api collabs announcement value documented for this operation.", "nullable": true } } }, "description": "Active announcement returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get the active collaboration announcement", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collabs/announcement' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/announcement', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collabs/announcement',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/collabs/history/overview": { "get": { "description": "Return aggregate counts and the recorded year range for public historical collaborations. This anonymous-safe overview contains no participant contact information or staff-only evidence.", "operationId": "getHistoricalCollabOverview", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "collabCount": 42, "creatorCount": 380, "endYear": 2026, "majorCount": 30, "miniCount": 12, "participantCount": 610, "startYear": 2022, "submissionCount": 1450 }, "schema": { "description": "Fields describing 200 response for api collabs history overview in Developer API requests and responses.", "properties": { "collabCount": { "description": "Number of collab records represented by this 200 response for api collabs history overview.", "type": "integer" }, "creatorCount": { "description": "Number of creator records represented by this 200 response for api collabs history overview.", "type": "integer" }, "endYear": { "description": "Numeric end year reported for this 200 response for api collabs history overview.", "nullable": true, "type": "integer" }, "majorCount": { "description": "Number of major records represented by this 200 response for api collabs history overview.", "type": "integer" }, "miniCount": { "description": "Number of mini records represented by this 200 response for api collabs history overview.", "type": "integer" }, "participantCount": { "description": "Number of participant records represented by this 200 response for api collabs history overview.", "type": "integer" }, "startYear": { "description": "Numeric start year reported for this 200 response for api collabs history overview.", "nullable": true, "type": "integer" }, "submissionCount": { "description": "Number of submission records represented by this 200 response for api collabs history overview.", "type": "integer" } }, "required": [ "collabCount", "majorCount", "miniCount", "creatorCount", "participantCount", "submissionCount" ], "type": "object" } } }, "description": "Historical catalog totals and recorded year range returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get the public historical collaboration overview", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collabs/history/overview' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/history/overview', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collabs/history/overview',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/collabs/{collabId}": { "get": { "description": "Return a visible live or historical collaboration by numeric identifier or slug. Participant, submission, evidence, management, and invitation fields are filtered according to the anonymous, member, owner, and staff visibility matrix.", "operationId": "getCollab", "parameters": [ { "description": "Collab Id provided in the path.", "example": "example-collab-id", "in": "path", "name": "collabId", "required": true, "schema": { "description": "Collab Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-07-01T10:00:00.000Z", "currentParticipant": null, "historicalParticipants": [], "id": 7, "mode": "LIVE", "participantCount": 19, "participants": [], "permissions": { "canAcceptInvite": false, "canCancelOwnRequest": false, "canDeclineInvite": false, "canEditOwnParticipant": false, "canManage": false, "canRequestJoin": false }, "releaseAt": "2026-07-19T16:00:00.000Z", "slug": "geen-n-geener-collab", "status": "RELEASED", "submissionCount": 69, "title": "Geen n Geener Collab", "updatedAt": "2026-07-19T18:00:00.000Z", "visibility": "PUBLIC" }, "schema": { "$ref": "#/components/schemas/CollabDetail" } } }, "description": "Collaboration detail returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get a collaboration event", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collabs/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collabs/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/collabs/{collabId}/participants/placeholder": { "post": { "description": "Upload and safety-check placeholder artwork for the caller’s participant record in an active collaboration. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadMyCollabParticipantPlaceholder", "parameters": [ { "description": "Collab Id provided in the path.", "example": "example-collab-id", "in": "path", "name": "collabId", "required": true, "schema": { "description": "Collab Id value documented for this operation.", "type": "string" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "placeholderImage": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "placeholderImage": { "description": "Placeholder Image associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "participant": { "displayOrder": 1, "id": 1, "status": "example", "submissions": [ {} ] }, "path": "uploads/collabs/placeholder.webp", "rating": "safe" }, "schema": { "$ref": "#/components/schemas/DeveloperCollabPlaceholderUploadResponse" } } }, "description": "Placeholder image uploaded.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } }, "operationConflict": { "summary": "Operation-specific error", "value": { "error": "The requested service is temporarily unavailable.", "errorCode": "SERVICE_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The operation is temporarily unavailable because a required service, dependency, or integration is unavailable. The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload a participant placeholder image", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collabs/123/participants/placeholder' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/123/participants/placeholder', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collabs/123/participants/placeholder',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/collabs/{collabId}/participants/self": { "delete": { "description": "Cancel the caller’s pending request or invitation to an active collaboration without affecting accepted participants. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "leaveCollab", "parameters": [ { "description": "Collab Id provided in the path.", "example": "example-collab-id", "in": "path", "name": "collabId", "required": true, "schema": { "description": "Collab Id value documented for this operation.", "type": "string" } } ], "responses": { "204": { "description": "Participant removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Participant state does not allow self-removal.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collaboration or participant not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove the current user's collaboration participant record", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/collabs/123/participants/self' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/123/participants/self', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/collabs/123/participants/self',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Update the caller’s own character, source, notes, and placeholder-description fields in an active collaboration. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateMyCollabParticipant", "parameters": [ { "description": "Collab Id provided in the path.", "example": "example-collab-id", "in": "path", "name": "collabId", "required": true, "schema": { "description": "Collab Id value documented for this operation.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "participant": { "displayOrder": 1, "id": 1, "status": "example", "submissions": [ {} ] } }, "schema": { "$ref": "#/components/schemas/DeveloperCollabParticipantResponse" } } }, "description": "Participant updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update the current user's collaboration participant record", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/collabs/123/participants/self' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/123/participants/self', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/collabs/123/participants/self',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collabs/{collabId}/requests": { "post": { "description": "Request participation in an open live collaboration or return the caller’s existing request without creating a duplicate participant. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "requestCollabJoin", "parameters": [ { "description": "Collab Id provided in the path.", "example": "example-collab-id", "in": "path", "name": "collabId", "required": true, "schema": { "description": "Collab Id value documented for this operation.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": {}, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "type": "object" } } }, "description": "Request payload for this operation.", "required": false }, "responses": { "200": { "content": { "application/json": { "example": { "participant": { "displayOrder": 1, "id": 1, "status": "example", "submissions": [ {} ] } }, "schema": { "$ref": "#/components/schemas/DeveloperCollabParticipantResponse" } } }, "description": "Existing join request or invitation updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "201": { "content": { "application/json": { "example": { "participant": { "displayOrder": 1, "id": 1, "status": "example", "submissions": [ {} ] } }, "schema": { "$ref": "#/components/schemas/DeveloperCollabParticipantResponse" } } }, "description": "New join request recorded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "The caller cannot request access to this collaboration.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collaboration not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Request to join a collaboration", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collabs/123/requests' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/123/requests', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collabs/123/requests',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collabs/{collabId}/showcase": { "get": { "description": "Return the public showcase entries for an eligible released collaboration. Placeholder and unreleased entries remain disabled for ordinary callers and can only be requested by authenticated staff.", "operationId": "getCollabShowcase", "parameters": [ { "description": "Collab Id provided in the path.", "example": "example-collab-id", "in": "path", "name": "collabId", "required": true, "schema": { "description": "Collab Id value documented for this operation.", "type": "string" } }, { "description": "Include Placeholders provided in the query.", "example": true, "in": "query", "name": "includePlaceholders", "schema": { "description": "Include Placeholders value documented for this operation.", "type": "boolean" } }, { "description": "Include Unreleased provided in the query.", "example": true, "in": "query", "name": "includeUnreleased", "schema": { "description": "Include Unreleased value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "collab": { "id": 7, "releaseAt": "2026-07-19T16:00:00.000Z", "slug": "geen-n-geener-collab", "status": "RELEASED", "title": "Geen n Geener Collab", "url": "https://arcenciel.io/collabs/geen-n-geener-collab" }, "entries": [ { "characterName": "Fluorite", "entryId": "submission:653", "modelId": 15087, "modelTitle": "Rebecca", "modelUrl": "https://arcenciel.io/models/15087", "participantId": 68, "profileUrl": "https://arcenciel.io/users/16", "sourceKind": "model", "status": "LINKED", "submissionId": 653, "thumbnailUrl": "https://uploads.arcenciel.io/uploads/images/example.w256.webp", "userId": 16, "username": "justTNP" } ] }, "schema": { "$ref": "#/components/schemas/CollabShowcase" } } }, "description": "Showcase data returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get collaboration showcase data", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collabs/123/showcase' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/123/showcase', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collabs/123/showcase',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/collabs/{collabId}/showcase/image": { "get": { "description": "Transfer a generated PNG showcase for an eligible released collaboration. Clients may use byte ranges, must honor Content-Range and the inline filename, and must not automatically retry an unchanged invalid range.", "operationId": "downloadCollabShowcaseImage", "parameters": [ { "description": "Collab Id provided in the path.", "example": "example-collab-id", "in": "path", "name": "collabId", "required": true, "schema": { "description": "Collab Id value documented for this operation.", "type": "string" } }, { "description": "Server-supported layout. Unknown values fall back to the default layout.", "example": "example-style", "in": "query", "name": "style", "schema": { "description": "Style value documented for this operation.", "type": "string" } }, { "description": "Requested output width; the runtime clamps values to the supported range.", "example": 1, "in": "query", "name": "width", "schema": { "description": "Width value documented for this operation.", "type": "integer" } }, { "description": "Include Placeholders provided in the query.", "example": true, "in": "query", "name": "includePlaceholders", "schema": { "description": "Include Placeholders value documented for this operation.", "type": "boolean" } }, { "description": "Include Unreleased provided in the query.", "example": true, "in": "query", "name": "includeUnreleased", "schema": { "description": "Include Unreleased value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "image/png": { "schema": { "description": "200 response for api collabs collab Id showcase image value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Showcase PNG returned.", "headers": { "Accept-Ranges": { "example": "bytes", "schema": { "type": "string" } }, "Content-Disposition": { "example": "inline; filename=\"collab-7-showcase.png\"", "schema": { "type": "string" } }, "Content-Length": { "schema": { "format": "int64", "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "image/png": { "schema": { "description": "206 response for api collabs collab Id showcase image value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Requested PNG byte range returned.", "headers": { "Accept-Ranges": { "example": "bytes", "schema": { "type": "string" } }, "Content-Disposition": { "example": "inline; filename=\"collab-7-showcase.png\"", "schema": { "type": "string" } }, "Content-Length": { "schema": { "format": "int64", "type": "integer" } }, "Content-Range": { "example": "bytes 0-1023/3084333", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "416": { "content": { "application/json": { "example": { "error": "Requested range is not satisfiable", "errorCode": "RANGE_NOT_SATISFIABLE", "retryable": false }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Requested byte range is not satisfiable for the current PNG representation.", "headers": { "Content-Range": { "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download a collaboration showcase image", "tags": [ "Collabs" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collabs/123/showcase/image' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collabs/123/showcase/image', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collabs/123/showcase/image',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/collections": { "get": { "description": "List collections visible to the caller with bounded pagination, discovery filters, relationship filters, item counts, and public owner metadata. Private and manageable views require the corresponding authenticated membership.", "operationId": "listCollections", "parameters": [ { "description": "Type provided in the query.", "example": "MODEL", "in": "query", "name": "type", "schema": { "description": "Type value documented for this operation. Supported values: `MODEL`, `IMAGE`.", "enum": [ "MODEL", "IMAGE" ], "type": "string" } }, { "description": "Filter by name, description, or slug.", "example": "landscape", "in": "query", "name": "search", "schema": { "description": "Search value documented for this operation.", "type": "string" } }, { "description": "Sorting strategy (default newest).", "example": "newest", "in": "query", "name": "sort", "schema": { "description": "Sort value documented for this operation. Supported values: `newest`, `updated`, `items`, `collaborators`, `alpha`.", "enum": [ "newest", "updated", "items", "collaborators", "alpha" ], "type": "string" } }, { "description": "Filter for collaborative collections.", "example": "true", "in": "query", "name": "collaborative", "schema": { "description": "Collaborative value documented for this operation. Supported values: `true`, `false`.", "enum": [ "true", "false" ], "type": "string" } }, { "description": "Filter by owner id.", "example": 1, "in": "query", "name": "ownerId", "schema": { "description": "Owner Id value documented for this operation.", "type": "integer" } }, { "description": "Use \"manageable\" to fetch collections you can manage (owner or collaborator).", "example": "public", "in": "query", "name": "scope", "schema": { "description": "Scope value documented for this operation. Supported values: `public`, `manageable`.", "enum": [ "public", "manageable" ], "type": "string" } }, { "description": "When scope=manageable, limit results by your role.", "example": "any", "in": "query", "name": "membership", "schema": { "description": "Membership value documented for this operation. Supported values: `any`, `owner`, `collaborator`.", "enum": [ "any", "owner", "collaborator" ], "type": "string" } }, { "description": "Requires authentication. Filter for collections you favorited or by creators you follow.", "example": "favorited", "in": "query", "name": "self", "schema": { "description": "Self value documented for this operation. Supported values: `favorited`, `followed`.", "enum": [ "favorited", "followed" ], "type": "string" } }, { "description": "Filter by visibility.", "example": "PUBLIC", "in": "query", "name": "visibility", "schema": { "description": "Visibility value documented for this operation. Supported values: `PUBLIC`, `UNLISTED`, `PRIVATE`.", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE" ], "type": "string" } }, { "description": "Fetch collections where this user is an owner or collaborator.", "example": 1, "in": "query", "name": "userId", "schema": { "description": "User Id value documented for this operation.", "type": "integer" } }, { "description": "Relationship filter applied when userId is provided (default any).", "example": "any", "in": "query", "name": "relationship", "schema": { "description": "Relationship value documented for this operation. Supported values: `any`, `owner`, `collaborator`.", "enum": [ "any", "owner", "collaborator" ], "type": "string" } }, { "description": "Page provided in the query.", "example": 1, "in": "query", "name": "page", "schema": { "description": "Page value documented for this operation.", "type": "integer" } }, { "description": "Limit provided in the query.", "example": 1, "in": "query", "name": "limit", "schema": { "description": "Limit value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "allowCollaborators": true, "collaboratorCount": 1, "collaborators": [], "createdAt": "2026-07-25T14:33:00.380Z", "favoriteCount": 0, "featured": "NONE", "id": 97, "imageCount": 0, "itemCount": 51, "itemPlacement": "APPEND", "lastUpdated": "2026-08-07T02:49:14.302Z", "modelCount": 51, "name": "Bold Bluenettes Collab", "selfFavorited": false, "slug": "bold-bluenettes-collab", "type": "MODEL", "visibility": "PUBLIC" } ], "limit": 20, "page": 1, "totalCount": 1, "totalPages": 1 }, "schema": { "$ref": "#/components/schemas/CollectionPage" } } }, "description": "Paged list of collections.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List collections", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collections' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collections',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a model or image collection with a generated slug, caller ownership, visibility, cover, and collaboration preferences. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "createCollection", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "allowCollaborators": true, "coverImage": "value", "coverImageRating": "safe", "description": "value", "itemPlacement": "APPEND", "name": "value", "type": "MODEL", "visibility": "PUBLIC" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "allowCollaborators": { "description": "Whether allow collaborators applies to this request payload.", "type": "boolean" }, "coverImage": { "description": "Path returned from the cover upload endpoint.", "type": "string" }, "coverImageRating": { "description": "Cover Image Rating associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `safe`, `questionable`, `sensitive`, `explicit`.", "enum": [ "safe", "questionable", "sensitive", "explicit" ], "type": "string" }, "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "itemPlacement": { "description": "Adjust the default placement for newly added items.", "enum": [ "APPEND", "PREPEND" ], "type": "string" }, "name": { "description": "Human-readable name for this request payload; it is not a stable identifier.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of request payload; clients should tolerate future values. Supported values: `MODEL`, `IMAGE`.", "enum": [ "MODEL", "IMAGE" ], "type": "string" }, "visibility": { "description": "Visibility associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `PUBLIC`, `UNLISTED`, `PRIVATE`.", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE" ], "type": "string" } }, "required": [ "name", "type" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "id": 84, "slug": "portrait-workflow" }, "schema": { "$ref": "#/components/schemas/DeveloperCollectionIdentity" } } }, "description": "Collection created.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Visibility not permitted for the user role.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a new collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collections' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"name\":\"value\",\"description\":\"value\",\"type\":\"MODEL\",\"visibility\":\"PUBLIC\",\"allowCollaborators\":true,\"itemPlacement\":\"APPEND\",\"coverImage\":\"value\",\"coverImageRating\":\"safe\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"name\": \"value\",\n \"description\": \"value\",\n \"type\": \"MODEL\",\n \"visibility\": \"PUBLIC\",\n \"allowCollaborators\": true,\n \"itemPlacement\": \"APPEND\",\n \"coverImage\": \"value\",\n \"coverImageRating\": \"safe\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collections',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"name\\\":\\\"value\\\",\\\"description\\\":\\\"value\\\",\\\"type\\\":\\\"MODEL\\\",\\\"visibility\\\":\\\"PUBLIC\\\",\\\"allowCollaborators\\\":true,\\\"itemPlacement\\\":\\\"APPEND\\\",\\\"coverImage\\\":\\\"value\\\",\\\"coverImageRating\\\":\\\"safe\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/collections/cover": { "post": { "description": "Upload one validated collection-cover image and return the managed relative path plus its safety rating. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadCollectionCover", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "coverImage": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "coverImage": { "description": "Cover Image associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" } }, "required": [ "coverImage" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "path": "uploads/collections/cover.webp", "rating": "safe" }, "schema": { "$ref": "#/components/schemas/DeveloperCollectionCoverUploadResponse" } } }, "description": "Cover processed and rated.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "No file uploaded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload and analyse a provisional collection cover", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collections/cover' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/cover', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collections/cover',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/collections/{collectionId}": { "delete": { "description": "Delete a caller-managed collection and its association records without deleting the referenced models or images. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "deleteCollection", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "responses": { "204": { "description": "Collection deleted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid identifier.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to delete this collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/collections/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/collections/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one collection visible to the caller with optional paged model and image items, collaborator summaries, counts, and caller-specific permissions. Private collections remain limited to members and privileged staff.", "operationId": "getCollection", "parameters": [ { "description": "Collection Id provided in the path.", "example": "example-collection-id", "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "string" } }, { "description": "Include Items provided in the query.", "example": "true", "in": "query", "name": "includeItems", "schema": { "description": "Include Items value documented for this operation. Supported values: `true`, `false`.", "enum": [ "true", "false" ], "type": "string" } }, { "description": "Model Limit provided in the query.", "example": 1, "in": "query", "name": "modelLimit", "schema": { "description": "Model Limit value documented for this operation.", "type": "integer" } }, { "description": "Model Offset provided in the query.", "example": 1, "in": "query", "name": "modelOffset", "schema": { "description": "Model Offset value documented for this operation. Minimum: 0.", "minimum": 0, "type": "integer" } }, { "description": "Image Limit provided in the query.", "example": 1, "in": "query", "name": "imageLimit", "schema": { "description": "Image Limit value documented for this operation.", "type": "integer" } }, { "description": "Image Offset provided in the query.", "example": 1, "in": "query", "name": "imageOffset", "schema": { "description": "Image Offset value documented for this operation. Minimum: 0.", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "allowCollaborators": true, "collaborators": [], "contributionRequest": null, "createdAt": "2026-07-25T14:33:00.380Z", "favoriteCount": 0, "featured": "NONE", "id": 97, "imageItems": [], "itemPlacement": "APPEND", "modelItems": [], "name": "Bold Bluenettes Collab", "pagination": { "images": { "nextOffset": null, "returned": 0, "total": 0 }, "models": { "nextOffset": null, "returned": 0, "total": 51 } }, "permissions": { "canContribute": false, "canManageCollaborators": false, "isCollaborator": false, "isOwner": false }, "selfFavorited": false, "slug": "bold-bluenettes-collab", "stats": { "imageCount": 0, "lastUpdated": "2026-08-07T02:49:14.302Z", "modelCount": 51, "totalItems": 51 }, "type": "MODEL", "visibility": "PUBLIC" }, "schema": { "$ref": "#/components/schemas/CollectionDetail" } } }, "description": "Collection detail payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Fetch a single collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collections/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collections/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update supported collection metadata, visibility, slug, cover, collaboration flag, and item placement. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateCollection", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "allowCollaborators": true, "coverImage": "value", "coverImageRating": "safe", "description": "value", "name": "value", "slug": "value", "visibility": "PUBLIC" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "allowCollaborators": { "description": "Whether allow collaborators applies to this request payload.", "type": "boolean" }, "coverImage": { "description": "Cover Image associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "coverImageRating": { "description": "Cover Image Rating associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `safe`, `questionable`, `sensitive`, `explicit`, ``.", "enum": [ "safe", "questionable", "sensitive", "explicit", "" ], "type": "string" }, "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "name": { "description": "Human-readable name for this request payload; it is not a stable identifier.", "type": "string" }, "slug": { "description": "Slug associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "visibility": { "description": "Visibility associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `PUBLIC`, `UNLISTED`, `PRIVATE`.", "enum": [ "PUBLIC", "UNLISTED", "PRIVATE" ], "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "id": 84, "slug": "portrait-workflow" }, "schema": { "$ref": "#/components/schemas/DeveloperCollectionIdentity" } } }, "description": "Collection updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload or no changes supplied.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to update this collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Slug already in use.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update collection metadata", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/collections/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"name\":\"value\",\"description\":\"value\",\"slug\":\"value\",\"coverImage\":\"value\",\"coverImageRating\":\"safe\",\"visibility\":\"PUBLIC\",\"allowCollaborators\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"name\": \"value\",\n \"description\": \"value\",\n \"slug\": \"value\",\n \"coverImage\": \"value\",\n \"coverImageRating\": \"safe\",\n \"visibility\": \"PUBLIC\",\n \"allowCollaborators\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/collections/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"name\\\":\\\"value\\\",\\\"description\\\":\\\"value\\\",\\\"slug\\\":\\\"value\\\",\\\"coverImage\\\":\\\"value\\\",\\\"coverImageRating\\\":\\\"safe\\\",\\\"visibility\\\":\\\"PUBLIC\\\",\\\"allowCollaborators\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/collaborators": { "post": { "description": "Add or update a collection collaborator with an explicit role while preserving owner and manager authorization rules. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "addCollectionCollaborator", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "role": "CONTRIBUTOR", "userId": 1 }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "role": { "description": "Access role represented by this request payload; use it for display and capability checks, not authentication. Supported values: `CONTRIBUTOR`, `MANAGER`.", "enum": [ "CONTRIBUTOR", "MANAGER" ], "type": "string" }, "userId": { "description": "Stable identifier for the user; use it in subsequent API calls instead of a display name.", "type": "integer" } }, "required": [ "userId" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "id": 1, "role": "example", "user": { "id": 42, "username": "rainbow-creator" } }, "schema": { "$ref": "#/components/schemas/CollectionCollaboratorSummary" } } }, "description": "Collaborator added or updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to manage collaborators.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Add or update a collaborator", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collections/123/collaborators' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"userId\":1,\"role\":\"CONTRIBUTOR\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/collaborators', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"userId\": 1,\n \"role\": \"CONTRIBUTOR\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collections/123/collaborators',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"userId\\\":1,\\\"role\\\":\\\"CONTRIBUTOR\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/collaborators/self": { "delete": { "description": "Remove the caller’s own non-owner collaborator relationship from a collection without altering its items. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "leaveCollection", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "responses": { "204": { "description": "Collaborator removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Leave a collection as collaborator", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/collections/123/collaborators/self' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/collaborators/self', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/collections/123/collaborators/self',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/collaborators/{collaboratorId}": { "delete": { "description": "Remove one non-owner collaborator after manager authorization while preserving the collection and referenced content. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "removeCollectionCollaborator", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } }, { "description": "Collaborator Id provided in the path.", "example": 1, "in": "path", "name": "collaboratorId", "required": true, "schema": { "description": "Collaborator Id value documented for this operation.", "type": "integer" } } ], "responses": { "204": { "description": "Collaborator removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid identifiers or action.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to manage collaborators.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection or collaborator not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove a collaborator from a collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/collections/123/collaborators/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/collaborators/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/collections/123/collaborators/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/contribution-requests": { "get": { "description": "List contribution requests for a collection the authenticated caller may manage. The operation never exposes requests to anonymous callers, ordinary non-manager members, or API keys without the CollectionsRead scope.", "operationId": "listCollectionContributionRequests", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "createdAt": "2026-08-07T09:00:00.000Z", "id": 42, "message": "I can contribute the matching model files.", "respondedAt": null, "respondedBy": null, "status": "PENDING", "user": { "id": 647, "username": "Hoseki" } } ], "schema": { "description": "Ordered 200 response for api collections collection id contribution requests values returned by this operation.", "items": { "$ref": "#/components/schemas/CollectionContributionRequest" }, "type": "array" } } }, "description": "Contribution requests for the collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List pending contribution requests", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsRead", "x-api-key-required-scope-mask": 16384, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/collections/123/contribution-requests' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/contribution-requests', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/collections/123/contribution-requests',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create or return the caller’s contribution request for a collection that currently accepts community contributors. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "requestCollectionContribution", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "message": "value" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "message": { "description": "Optional request message (max 500 characters).", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation." }, "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T10:00:00.000Z", "id": 1, "message": "example", "respondedAt": "2026-08-07T10:00:00.000Z", "respondedBy": { "id": 42, "username": "rainbow-creator" }, "status": "example", "user": { "id": 42, "username": "rainbow-creator" } }, "schema": { "$ref": "#/components/schemas/CollectionContributionRequest" } } }, "description": "Existing pending request returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "201": { "content": { "application/json": { "example": { "createdAt": "2026-08-07T10:00:00.000Z", "id": 1, "message": "example", "respondedAt": "2026-08-07T10:00:00.000Z", "respondedBy": { "id": 42, "username": "rainbow-creator" }, "status": "example", "user": { "id": 42, "username": "rainbow-creator" } }, "schema": { "$ref": "#/components/schemas/CollectionContributionRequest" } } }, "description": "Contribution request created.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Request not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Request collaborator access for a collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collections/123/contribution-requests' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"message\":\"value\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/contribution-requests', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"message\": \"value\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collections/123/contribution-requests',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"message\\\":\\\"value\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/contribution-requests/self": { "delete": { "description": "Cancel the caller’s pending contribution request for one collection without changing collaborator access. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "cancelCollectionContributionRequest", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "responses": { "204": { "description": "Request cancelled.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid identifier.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "No pending request to cancel or collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Cancel the current user's pending collaboration request", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/collections/123/contribution-requests/self' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/contribution-requests/self', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/collections/123/contribution-requests/self',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/contribution-requests/{requestId}": { "patch": { "description": "Approve or decline one pending contribution request and return the resulting request and optional collaborator. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "respondCollectionContributionRequest", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } }, { "description": "Request Id provided in the path.", "example": 1, "in": "path", "name": "requestId", "required": true, "schema": { "description": "Request Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "action": "approve" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "action": { "description": "Action associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `approve`, `decline`.", "enum": [ "approve", "decline" ], "type": "string" } }, "required": [ "action" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "collaborator": { "id": 1, "role": "example", "user": { "id": 42, "username": "rainbow-creator" } }, "request": { "createdAt": "2026-08-07T10:00:00.000Z", "id": 1, "message": "example", "respondedAt": "2026-08-07T10:00:00.000Z", "respondedBy": { "id": 42, "username": "rainbow-creator" }, "status": "example", "user": { "id": 42, "username": "rainbow-creator" } } }, "schema": { "$ref": "#/components/schemas/DeveloperCollectionContributionDecisionResponse" } } }, "description": "Request processed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to manage collaborators.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Request or collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Approve or decline a contribution request", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/collections/123/contribution-requests/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"action\":\"approve\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/contribution-requests/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"action\": \"approve\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/collections/123/contribution-requests/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"action\\\":\\\"approve\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/favorited": { "patch": { "description": "Set the current caller’s favorite state for a visible collection using an explicit boolean. Repeating the same desired state cannot reverse it.", "operationId": "setCollectionFavorite", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "favorite": true }, "schema": { "properties": { "favorite": { "description": "The desired favorite state.", "example": true, "type": "boolean" } }, "required": [ "favorite" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Favorite status updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Favorite or unfavorite a collection", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/collections/123/favorited' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"favorite\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/favorited', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"favorite\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/collections/123/favorited',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"favorite\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "social-favorite", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/items": { "post": { "description": "Add a bounded set of visible model or image identifiers to a collection and report added, skipped, and rejected identifiers. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "addCollectionItems", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "items": [ 1 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "items": { "description": "Ordered items entries included with this request payload; an empty list means none are available.", "items": { "description": "Numeric items item reported for this items.", "type": "integer" }, "maxItems": 200, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "added": [ 52, 61 ], "addedCount": 2, "collectionId": 84, "createdItemIds": [ 701, 702 ], "duplicate": [ 18 ], "duplicateCount": 1, "missing": [ 999999 ], "missingCount": 1, "type": "MODEL" }, "schema": { "$ref": "#/components/schemas/DeveloperCollectionItemsMutationResponse" } } }, "description": "Items processed for the collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to modify this collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Add items to a collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collections/123/items' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"items\":[1]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/items', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"items\": [\n 1\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collections/123/items',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"items\\\":[1]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/items/order": { "patch": { "description": "Apply explicit sequence values to existing collection items after validating that every identifier belongs to the collection. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "reorderCollectionItems", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "order": [ { "id": 1, "order": 1 } ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "order": { "description": "Ordered order entries included with this request payload; an empty list means none are available.", "items": { "description": "Structured order item details for this order.", "properties": { "id": { "description": "Stable identifier for the order item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "order": { "description": "Numeric order reported for this order item.", "type": "integer" } }, "required": [ "id", "order" ], "type": "object" }, "type": "array" } }, "required": [ "order" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "204": { "description": "Order updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to modify this collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection or an item was not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Override the item ordering for a collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/collections/123/items/order' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"order\":[{\"id\":1,\"order\":1}]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/items/order', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"order\": [\n {\n \"id\": 1,\n \"order\": 1\n }\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/collections/123/items/order',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"order\\\":[{\\\"id\\\":1,\\\"order\\\":1}]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/items/resequence": { "post": { "description": "Reassign collection item sequence values from their current order to restore a compact deterministic ordering. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "resequenceCollectionItems", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "mode": "newest" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "mode": { "description": "Manually override the resequencing mode. Defaults to the collection preference.", "enum": [ "newest", "oldest" ], "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": false }, "responses": { "204": { "description": "Resequencing completed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to modify this collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Reapply an automatic ordering to existing collection items", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/collections/123/items/resequence' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"mode\":\"newest\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/items/resequence', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"mode\": \"newest\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/collections/123/items/resequence',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"mode\\\":\\\"newest\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/collections/{collectionId}/items/{itemId}": { "delete": { "description": "Remove one model or image association from a caller-managed collection without deleting the referenced resource. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "removeCollectionItem", "parameters": [ { "description": "Collection Id provided in the path.", "example": 1, "in": "path", "name": "collectionId", "required": true, "schema": { "description": "Collection Id value documented for this operation.", "type": "integer" } }, { "description": "Item Id provided in the path.", "example": 1, "in": "path", "name": "itemId", "required": true, "schema": { "description": "Item Id value documented for this operation.", "type": "integer" } } ], "responses": { "204": { "description": "Item removed from the collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid identifiers.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to modify this collection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Collection or item not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove an item from a collection", "tags": [ "Collections" ], "x-api-key-required-scope": "CollectionsWrite", "x-api-key-required-scope-mask": 32768, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/collections/123/items/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/collections/123/items/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/collections/123/items/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/creators/{id}/stats": { "get": { "description": "Return the authenticated creator statistics available to the caller. Standard creators receive a bounded preview, supporters receive advanced ranges, and staff may inspect another creator.", "operationId": "getCreatorStats", "parameters": [ { "description": "The creator's user ID.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "ISO timestamp that marks the inclusive start of the range. Ignored for the standard seven-day preview.", "example": "2026-07-28T10:00:00.000Z", "in": "query", "name": "startDate", "required": false, "schema": { "description": "Start Date value documented for this operation. Format: date-time.", "format": "date-time", "type": "string" } }, { "description": "ISO timestamp that marks the inclusive end of the range. Ignored for the standard seven-day preview.", "example": "2026-07-28T10:00:00.000Z", "in": "query", "name": "endDate", "required": false, "schema": { "description": "End Date value documented for this operation. Format: date-time.", "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "appliedRange": { "end": "2026-08-07T12:00:00.000Z", "start": "2026-08-01T00:00:00.000Z" }, "comments": 4, "downloadEventsTotal": 42, "downloadPerformance": { "returningDownloaderRate": 0.2581, "returningDownloaders": 8 }, "downloadSeries": [ { "count": 12, "date": "2026-08-01", "events": 12, "uniqueDownloaders": 10 } ], "downloadsTotal": 42, "favorites": { "articles": 2, "models": 9 }, "followers": 17, "meta": { "accessTier": "SUPPORTER", "advancedAccess": true, "cache": { "expiresAt": "2026-08-07T12:05:00.000Z", "hit": false, "ttlMs": 300000 }, "maxWindowDays": 31, "rangeClamped": false, "standardWindowDays": 7 }, "rangeBounds": { "max": "2026-08-07T12:00:00.000Z", "min": "2025-01-01T00:00:00.000Z" }, "reactions": { "dislikes": 1, "hearts": 10, "likes": 6 }, "topModels": [ { "downloads": 20, "events": 20, "modelId": 14474, "title": "Landscape XL", "uniqueDownloaders": 15 } ], "uniqueDownloadersTotal": 31, "uniqueDownloads": 31 }, "schema": { "$ref": "#/components/schemas/CreatorStatsResponse" } } }, "description": "Aggregated statistics for the requested creator.", "headers": { "X-Creator-Stats-Cache": { "description": "HIT when the response came from the short-lived private cache, otherwise MISS.", "schema": { "type": "string" } }, "X-Creator-Stats-Window": { "description": "Maximum number of days available to this caller.", "schema": { "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Creator not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve aggregated statistics for a creator.", "tags": [ "Users" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/creators/123/stats' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/creators/123/stats', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/creators/123/stats',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/emotes": { "get": { "description": "List the public emote catalogue used by community text surfaces. Authentication is optional and integrations should discover current records instead of hard-coding emote identifiers.", "operationId": "listEmotes", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": [ { "animated": false, "id": 7, "name": "poggers", "url": "/uploads/emotes/poggers.png" } ], "schema": { "description": "Ordered 200 response for api emotes values returned by this operation.", "items": { "$ref": "#/components/schemas/Emote" }, "type": "array" } } }, "description": "Array of emotes", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List all emotes", "tags": [ "Emotes" ], "x-api-key-required-scope": "None", "x-api-key-scope-exempt": true, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/emotes' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/emotes', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/emotes',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/feedback": { "post": { "description": "Submit authenticated product feedback with up to six validated attachments. Reuse an Idempotency-Key and identical multipart payload when retrying an ambiguous request.", "operationId": "createFeedback", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "category": "BUG", "description": "The browser remains at 99 percent after the final chunk was transferred.", "source": "/models/upload", "title": "Upload progress stalls near completion" }, "schema": { "properties": { "attachments": { "description": "Optional validated screenshots, documents, archives, or short media evidence.", "items": { "format": "binary", "type": "string" }, "maxItems": 6, "type": "array" }, "category": { "description": "Feedback category. Known values: BUG, FEATURE, UX, PERFORMANCE, MODERATION, OTHER. Clients must tolerate future values.", "example": "BUG", "type": "string" }, "contactDiscord": { "description": "Optional reporter contact hint.", "maxLength": 120, "type": "string" }, "description": { "description": "Detailed feedback and reproduction context.", "maxLength": 4000, "minLength": 20, "type": "string" }, "source": { "description": "Related HTTPS URL or Arc en Ciel path.", "maxLength": 500, "type": "string" }, "title": { "description": "Short reproducible feedback title.", "maxLength": 140, "minLength": 5, "type": "string" } }, "required": [ "category", "title", "description" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "assignee": { "id": 42, "username": "aurora" }, "attachments": [ { "downloadPath": "/api/feedback/FB-9A2C13/attachments/cm4attachment01", "expiresAt": "2026-08-07T10:00:00.000Z", "fileName": "console-log.txt", "id": "cm4attachment01", "mimeType": "text/plain", "sizeBytes": 1842 } ], "category": "BUG", "contactDiscord": "aurora", "createdAt": "2026-08-07T10:00:00.000Z", "description": "The browser remains at 99 percent after the final chunk was transferred.", "internalNotes": null, "priority": "MEDIUM", "publicId": "FB-9A2C13", "reporter": { "id": 42, "username": "aurora" }, "resolvedAt": null, "sourcePath": "/models/upload", "sourceUrl": "https://arcenciel.io/models/upload", "status": "OPEN", "title": "Upload progress stalls near completion", "updatedAt": "2026-08-07T10:00:00.000Z", "updatedBy": { "id": 42, "username": "aurora" } }, "schema": { "$ref": "#/components/schemas/DeveloperFeedback" } } }, "description": "Feedback created", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Submit a feedback item", "tags": [ "Feedback" ], "x-api-key-required-scope": "FeedbackWrite", "x-api-key-required-scope-mask": 4194304, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/feedback' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/feedback', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/feedback',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 12, "policyId": "feedback-submit", "scope": "user, trusted API key, or client IP", "windowSeconds": 600 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/feedback/me": { "get": { "description": "List up to 100 feedback cases submitted by the authenticated caller. Other users’ cases and staff-only internal notes are never returned.", "operationId": "listMyFeedback", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": [ { "assignee": { "id": 42, "username": "aurora" }, "attachments": [ { "downloadPath": "/api/feedback/FB-9A2C13/attachments/cm4attachment01", "expiresAt": "2026-08-07T10:00:00.000Z", "fileName": "console-log.txt", "id": "cm4attachment01", "mimeType": "text/plain", "sizeBytes": 1842 } ], "category": "BUG", "contactDiscord": "aurora", "createdAt": "2026-08-07T10:00:00.000Z", "description": "The browser remains at 99 percent after the final chunk was transferred.", "internalNotes": null, "priority": "MEDIUM", "publicId": "FB-9A2C13", "reporter": { "id": 42, "username": "aurora" }, "resolvedAt": null, "sourcePath": "/models/upload", "sourceUrl": "https://arcenciel.io/models/upload", "status": "OPEN", "title": "Upload progress stalls near completion", "updatedAt": "2026-08-07T10:00:00.000Z", "updatedBy": { "id": 42, "username": "aurora" } } ], "schema": { "items": { "$ref": "#/components/schemas/DeveloperFeedback" }, "type": "array" } } }, "description": "Feedback list", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List feedback submitted by the current user", "tags": [ "Feedback" ], "x-api-key-required-scope": "FeedbackRead", "x-api-key-required-scope-mask": 2097152, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/feedback/me' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/feedback/me', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/feedback/me',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/feedback/{publicId}": { "delete": { "description": "Delete a feedback case owned by the authenticated caller, including its stored attachment files. Staff may delete a case through the same audited operation.", "operationId": "deleteFeedback", "parameters": [ { "description": "Public Id provided in the path.", "example": "FB-9A2C13", "in": "path", "name": "publicId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Feedback deleted." }, "schema": { "$ref": "#/components/schemas/DeveloperFeedbackDeleteResponse" } } }, "description": "Feedback deleted", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Feedback not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete one feedback item", "tags": [ "Feedback" ], "x-api-key-required-scope": "FeedbackWrite", "x-api-key-required-scope-mask": 4194304, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/feedback/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/feedback/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/feedback/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one feedback case to its reporter or staff. Reporter contact data is case-bound and internal moderation notes remain null for ordinary callers.", "operationId": "getFeedback", "parameters": [ { "description": "Public Id provided in the path.", "example": "FB-9A2C13", "in": "path", "name": "publicId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "assignee": { "id": 42, "username": "aurora" }, "attachments": [ { "downloadPath": "/api/feedback/FB-9A2C13/attachments/cm4attachment01", "expiresAt": "2026-08-07T10:00:00.000Z", "fileName": "console-log.txt", "id": "cm4attachment01", "mimeType": "text/plain", "sizeBytes": 1842 } ], "category": "BUG", "contactDiscord": "aurora", "createdAt": "2026-08-07T10:00:00.000Z", "description": "The browser remains at 99 percent after the final chunk was transferred.", "internalNotes": null, "priority": "MEDIUM", "publicId": "FB-9A2C13", "reporter": { "id": 42, "username": "aurora" }, "resolvedAt": null, "sourcePath": "/models/upload", "sourceUrl": "https://arcenciel.io/models/upload", "status": "OPEN", "title": "Upload progress stalls near completion", "updatedAt": "2026-08-07T10:00:00.000Z", "updatedBy": { "id": 42, "username": "aurora" } }, "schema": { "$ref": "#/components/schemas/DeveloperFeedback" } } }, "description": "Feedback detail", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Feedback not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get one feedback item", "tags": [ "Feedback" ], "x-api-key-required-scope": "FeedbackRead", "x-api-key-required-scope-mask": 2097152, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/feedback/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/feedback/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/feedback/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/feedback/{publicId}/attachments/{attachmentId}": { "get": { "description": "Stream a non-expired feedback attachment to the original reporter or staff. Honor the returned media type and Content-Disposition filename; attachment URLs are private.", "operationId": "downloadFeedbackAttachment", "parameters": [ { "description": "Public Id provided in the path.", "example": "FB-9A2C13", "in": "path", "name": "publicId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Attachment Id provided in the path.", "example": "ev-01HZX3", "in": "path", "name": "attachmentId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Set to 1, true, or yes to request attachment disposition instead of inline preview.", "example": "1", "in": "query", "name": "download", "required": false, "schema": { "enum": [ "1", "true", "yes" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "format": "binary", "type": "string" } }, "application/octet-stream": { "schema": { "format": "binary", "type": "string" } }, "application/pdf": { "schema": { "format": "binary", "type": "string" } }, "application/x-7z-compressed": { "schema": { "format": "binary", "type": "string" } }, "application/x-rar-compressed": { "schema": { "format": "binary", "type": "string" } }, "application/zip": { "schema": { "format": "binary", "type": "string" } }, "image/gif": { "schema": { "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "format": "binary", "type": "string" } }, "image/png": { "schema": { "format": "binary", "type": "string" } }, "image/webp": { "schema": { "format": "binary", "type": "string" } }, "text/markdown": { "schema": { "format": "binary", "type": "string" } }, "text/plain": { "schema": { "format": "binary", "type": "string" } }, "video/mp4": { "schema": { "format": "binary", "type": "string" } }, "video/quicktime": { "schema": { "format": "binary", "type": "string" } }, "video/webm": { "schema": { "format": "binary", "type": "string" } } }, "description": "Complete private attachment stream.", "headers": { "Accept-Ranges": { "description": "Indicates byte-range support when available.", "schema": { "example": "bytes", "type": "string" } }, "Content-Disposition": { "description": "Sanitized original filename and inline or attachment disposition.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "application/json": { "schema": { "format": "binary", "type": "string" } }, "application/octet-stream": { "schema": { "format": "binary", "type": "string" } }, "application/pdf": { "schema": { "format": "binary", "type": "string" } }, "application/x-7z-compressed": { "schema": { "format": "binary", "type": "string" } }, "application/x-rar-compressed": { "schema": { "format": "binary", "type": "string" } }, "application/zip": { "schema": { "format": "binary", "type": "string" } }, "image/gif": { "schema": { "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "format": "binary", "type": "string" } }, "image/png": { "schema": { "format": "binary", "type": "string" } }, "image/webp": { "schema": { "format": "binary", "type": "string" } }, "text/markdown": { "schema": { "format": "binary", "type": "string" } }, "text/plain": { "schema": { "format": "binary", "type": "string" } }, "video/mp4": { "schema": { "format": "binary", "type": "string" } }, "video/quicktime": { "schema": { "format": "binary", "type": "string" } }, "video/webm": { "schema": { "format": "binary", "type": "string" } } }, "description": "Requested byte range of the private attachment.", "headers": { "Content-Disposition": { "description": "Sanitized original filename.", "schema": { "type": "string" } }, "Content-Range": { "description": "Returned byte range and complete attachment size.", "schema": { "example": "bytes 0-1023/4096", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Attachment not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "410": { "description": "Attachment expired", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "416": { "description": "Requested byte range is not satisfiable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "View or download one feedback attachment", "tags": [ "Feedback" ], "x-api-key-required-scope": "FeedbackRead", "x-api-key-required-scope-mask": 2097152, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/feedback/123/attachments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/feedback/123/attachments/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/feedback/123/attachments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/autotag/interrogate": { "post": { "description": "Upload one validated image and return generator prompt tags inferred for the authenticated caller.", "operationId": "interrogateGeneratorImage", "parameters": [], "requestBody": { "content": { "multipart/form-data": { "example": { "image": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "image": { "description": "Image associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" } }, "required": [ "image" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "rating": "safe", "source": "upload", "tagCount": 1, "tags": [ "value" ] }, "schema": { "description": "Fields describing 200 response for api generator autotag interrogate in Developer API requests and responses.", "properties": { "rating": { "description": "Content-safety rating assigned to this 200 response for api generator autotag interrogate; callers must still apply their own audience policy. Supported values: `safe`, `questionable`, `sensitive`, `explicit`, `unknown`.", "enum": [ "safe", "questionable", "sensitive", "explicit", "unknown" ], "type": "string" }, "source": { "description": "Source associated with this 200 response for api generator autotag interrogate; preserve server-returned values when passing them to another operation. Supported values: `upload`.", "enum": [ "upload" ], "type": "string" }, "tagCount": { "description": "Number of tag records represented by this 200 response for api generator autotag interrogate.", "type": "integer" }, "tags": { "description": "Ordered tags entries included with this 200 response for api generator autotag interrogate; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" } }, "required": [ "source", "rating", "tags", "tagCount" ], "type": "object" } } }, "description": "Tags generated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing upload or invalid input.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Role not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "413": { "description": "Uploaded image too large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "description": "Tagger could not process image.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Autotagger unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Interrogate uploaded image with autotagger (artist+)", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/autotag/interrogate' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/autotag/interrogate', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/autotag/interrogate',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/generator/autotag/interrogate-url": { "post": { "description": "Fetch one supported image URL through the guarded media pipeline and return inferred generator prompt tags.", "operationId": "interrogateGeneratorImageUrl", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "imageUrl": "https://cdn.discordapp.com/attachments/123/example.png" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "imageUrl": { "description": "URL for the image url associated with this request payload; do not persist temporary signed query parameters. Format: uri.", "example": "https://cdn.discordapp.com/attachments/123/example.png", "format": "uri", "type": "string" } }, "required": [ "imageUrl" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "contentType": "value", "imageUrl": "https://arcenciel.io", "rating": "safe", "size": 1, "source": "url", "tagCount": 1, "tags": [ "value" ] }, "schema": { "description": "Fields describing 200 response for api generator autotag interrogate url in Developer API requests and responses.", "properties": { "contentType": { "description": "Discriminator identifying the kind of 200 response for api generator autotag interrogate url; clients should tolerate future values.", "type": "string" }, "imageUrl": { "description": "URL for the image url associated with this 200 response for api generator autotag interrogate url; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "type": "string" }, "rating": { "description": "Content-safety rating assigned to this 200 response for api generator autotag interrogate url; callers must still apply their own audience policy. Supported values: `safe`, `questionable`, `sensitive`, `explicit`, `unknown`.", "enum": [ "safe", "questionable", "sensitive", "explicit", "unknown" ], "type": "string" }, "size": { "description": "Size of the associated 200 response for api generator autotag interrogate url content in the unit indicated by the field name.", "type": "integer" }, "source": { "description": "Source associated with this 200 response for api generator autotag interrogate url; preserve server-returned values when passing them to another operation. Supported values: `url`.", "enum": [ "url" ], "type": "string" }, "tagCount": { "description": "Number of tag records represented by this 200 response for api generator autotag interrogate url.", "type": "integer" }, "tags": { "description": "Ordered tags entries included with this 200 response for api generator autotag interrogate url; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" } }, "required": [ "source", "rating", "tags", "tagCount", "imageUrl", "contentType", "size" ], "type": "object" } } }, "description": "Tags generated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid URL, unsafe URL, or fetch failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Role not allowed or host not allowlisted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "413": { "description": "Remote image too large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "415": { "description": "Remote content type is not a supported image format.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "description": "Tagger could not process image.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "502": { "description": "Remote fetch or autotagger unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Interrogate image from allowlisted URL (artist+)", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/autotag/interrogate-url' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"imageUrl\":\"https://cdn.discordapp.com/attachments/123/example.png\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/autotag/interrogate-url', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"imageUrl\": \"https://cdn.discordapp.com/attachments/123/example.png\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/autotag/interrogate-url',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"imageUrl\\\":\\\"https://cdn.discordapp.com/attachments/123/example.png\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/generator/catalog": { "get": { "deprecated": true, "description": "List the image-generator model catalogue visible to the caller, including supported checkpoints, LoRAs, capabilities, and availability metadata.", "operationId": "getGeneratorCatalog", "parameters": [ { "description": "Include Loras provided in the query.", "example": false, "in": "query", "name": "includeLoras", "schema": { "default": false, "description": "Include Loras value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "adetailer": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ], "checkpoints": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ], "loras": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ] }, "schema": { "$ref": "#/components/schemas/GeneratorModelCatalog" } } }, "description": "Model catalog payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Legacy alias for generator model catalog", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/catalog' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/catalog', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/catalog',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/compare-runs/{id}": { "get": { "description": "Return one caller-owned image comparison run and the jobs, axes, state, and grid metadata associated with it.", "operationId": "getGeneratorCompareRun", "parameters": [ { "description": "Id provided in the path.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "compareRun": { "completedCount": 1, "cost": { "budgetProfile": "value", "dailyUsage": 1, "estimatedGpuMs": 1, "estimatedVramMb": 1, "jobs": 1, "queueSlots": 1, "weight": 1 }, "count": 1, "createdAt": 1, "failedCount": 1, "grid": { "downloadUrl": "value", "height": 1, "previewHeight": 1, "previewRelativePath": "value", "previewUpdatedAt": 1, "previewWidth": 1, "reason": "value", "relativePath": "value", "status": "pending", "updatedAt": 1, "url": "value", "width": 1 }, "id": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "modelNames": [ "value" ], "pendingCount": 1, "seed": 1, "status": "queued", "updatedAt": 1 }, "jobs": [ { "job": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "attempts": 1, "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cancelled": true, "cfg": 1, "comfy": { "messages": [ {} ], "nodeErrors": [ {} ], "status": "value" }, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "start": 1, "strength": 1 } ], "createdAt": 1, "deletedAt": 1, "deletedByUserId": 1, "denoise": 1, "diagnostics": { "adetailer": {}, "adetailerBridge": { "failed": true, "reason": "value", "updatedAt": 1 }, "attentionCouple": {}, "historyTimeoutMs": 1, "workflowCaptured": true }, "error": "value", "expiresAt": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "id": "value", "imagePath": "value", "loraName": "value", "loras": [ { "name": "value", "weight": 1 } ], "metadata": {}, "mode": "txt2img", "modelCapabilities": [ "value" ], "modelName": "value", "negativePrompt": "value", "outputToken": "value", "outputs": [ { "filename": "value", "subfolder": "value", "type": "value" } ], "outputsExpiredAt": 1, "position": 1, "priority": 1, "progress": { "detail": { "elapsedMs": 1, "max": 1, "nodeId": "value", "ratio": 1, "source": "comfy_progress", "timeoutMs": 1, "value": 1 }, "etaMs": 1, "percent": 1, "phase": "queued", "updatedAt": 1 }, "prompt": "value", "promptControl": { "enabled": true, "mode": "manual", "source": "explicit" }, "publishedOutputs": [ "value" ], "queueEtaMs": 1, "rfShift": 1, "role": "value", "safety": { "error": "value", "outputs": {}, "reason": "value", "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "seed": 1, "status": "queued", "steps": 1, "storage": { "errors": [ { "error": "value", "path": "value" } ], "status": "value", "storedAt": 1 }, "taggerTags": [ "value" ], "tags": [ "value" ], "updatedAt": 1, "upscaleModelName": "value", "upscaleProfiles": [ { "denoise": 1, "modelName": "value" } ], "upscaleTargetHeight": 1, "upscaleTargetWidth": 1, "userId": 1, "vaeName": "value", "weight": 1, "width": 1 }, "position": 1, "queueEtaMs": 1 } ] }, "schema": { "$ref": "#/components/schemas/GeneratorCompareResponse" } } }, "description": "Compare run aggregate.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Compare run not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get a compare run aggregate", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/compare-runs/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/compare-runs/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/compare-runs/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/compare-runs/{id}/grid": { "get": { "description": "Return the generated comparison grid image for a completed caller-owned comparison run.", "operationId": "getGeneratorCompareGrid", "parameters": [ { "description": "Id provided in the path.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "image/webp": { "schema": { "description": "200 response for api generator compare runs id grid value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "WebP compare grid preview.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "One or more child outputs are safety restricted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Grid is unavailable or outputs are missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Compare run is still queued/running.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Render the compare run grid preview", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/compare-runs/123/grid' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/compare-runs/123/grid', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/compare-runs/123/grid',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/compare-runs/{id}/grid/download": { "get": { "description": "Download the generated comparison grid image for a completed caller-owned comparison run with an attachment filename.", "operationId": "downloadGeneratorCompareGrid", "parameters": [ { "description": "Id provided in the path.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "image/png": { "schema": { "description": "200 response for api generator compare runs id grid download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "PNG compare grid attachment.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "One or more child outputs are safety restricted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Grid is unavailable or outputs are missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Compare run is still queued/running.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download the compare run grid image", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/compare-runs/123/grid/download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/compare-runs/123/grid/download', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/compare-runs/123/grid/download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/events": { "get": { "description": "Open a server-sent event stream for caller-owned image-generation job state changes. Clients should reconnect with bounded backoff.", "operationId": "streamGeneratorEvents", "parameters": [], "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "200 response for api generator events value documented for this operation.", "example": "event: connected\ndata: {\"ok\":true}\n\nevent: job\ndata: {\"job\":{\"id\":\"...\",\"status\":\"running\"},\"position\":1,\"queueEtaMs\":12000}\n\nevent: heartbeat\ndata: {\"ts\":1710000000000}\n", "type": "string" } } }, "description": "Active text/event-stream connection.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated (response is typically empty if auth fails before stream handshake).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Stream generator events (SSE)", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/events' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/events', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/events',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/jobs": { "get": { "description": "List the authenticated caller’s image-generation jobs with bounded pagination, state, progress, and output summaries.", "operationId": "listGeneratorJobs", "parameters": [ { "description": "Take provided in the query.", "example": 20, "in": "query", "name": "take", "schema": { "default": 20, "description": "Take value documented for this operation. Minimum: 1. Maximum: 100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from previous response (`gc:*` composite cursor supported; legacy ids still accepted).", "example": "next-page", "in": "query", "name": "cursor", "schema": { "description": "Cursor value documented for this operation.", "type": "string" } }, { "description": "Comma-separated values (`queued,running,completed,failed`).", "example": "example-status", "in": "query", "name": "status", "schema": { "description": "Status value documented for this operation.", "type": "string" } }, { "description": "Comma-separated values (`txt2img,img2img,inpaint`).", "example": "example-mode", "in": "query", "name": "mode", "schema": { "description": "Mode value documented for this operation.", "type": "string" } }, { "description": "Text search alias for `query`.", "example": "landscape", "in": "query", "name": "q", "schema": { "description": "Q value documented for this operation.", "type": "string" } }, { "description": "Text search across prompt/negativePrompt/model fields.", "example": "landscape", "in": "query", "name": "query", "schema": { "description": "Query value documented for this operation.", "type": "string" } }, { "description": "Comma-separated tag filter.", "example": "example-tags", "in": "query", "name": "tags", "schema": { "description": "Tags value documented for this operation.", "type": "string" } }, { "description": "Tag Source provided in the query.", "example": "manual", "in": "query", "name": "tagSource", "schema": { "description": "Tag Source value documented for this operation. Supported values: `manual`, `auto`, `any`.", "enum": [ "manual", "auto", "any" ], "type": "string" } }, { "description": "Tag Mode provided in the query.", "example": "any", "in": "query", "name": "tagMode", "schema": { "description": "Tag Mode value documented for this operation. Supported values: `any`, `all`.", "enum": [ "any", "all" ], "type": "string" } }, { "description": "Accepts full datetime or `YYYY-MM-DD`.", "example": "2026-07-28T10:00:00.000Z", "in": "query", "name": "createdFrom", "schema": { "description": "Inclusive UTC creation timestamp used as the lower bound when filtering generator jobs.", "example": "2026-07-28T10:00:00.000Z", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T.*)?$", "type": "string" } }, { "description": "Accepts full datetime or `YYYY-MM-DD`.", "example": "2026-07-28T10:00:00.000Z", "in": "query", "name": "createdTo", "schema": { "description": "Inclusive UTC creation timestamp used as the upper bound when filtering generator jobs.", "example": "2026-07-28T10:00:00.000Z", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T.*)?$", "type": "string" } }, { "description": "Boolean filter (`true/false`, `1/0`, `yes/no`, `on/off`).", "example": true, "in": "query", "name": "hasOutputs", "schema": { "description": "Has Outputs value documented for this operation.", "type": "boolean" } }, { "description": "Boolean filter (`true/false`, `1/0`, `yes/no`, `on/off`).\nEvaluates presence of legacy `loraName` on jobs.\n", "example": true, "in": "query", "name": "hasLoras", "schema": { "description": "Has Loras value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "jobs": [ { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "attempts": 1, "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cancelled": true, "cfg": 1, "comfy": { "messages": [ {} ], "nodeErrors": [ {} ], "status": "value" }, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "start": 1, "strength": 1 } ], "createdAt": 1, "deletedAt": 1, "deletedByUserId": 1, "denoise": 1, "diagnostics": { "adetailer": {}, "adetailerBridge": { "failed": true, "reason": "value", "updatedAt": 1 }, "attentionCouple": {}, "historyTimeoutMs": 1, "workflowCaptured": true }, "error": "value", "expiresAt": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "id": "value", "imagePath": "value", "loraName": "value", "loras": [ { "name": "value", "weight": 1 } ], "metadata": {}, "mode": "txt2img", "modelCapabilities": [ "value" ], "modelName": "value", "negativePrompt": "value", "outputToken": "value", "outputs": [ { "filename": "value", "subfolder": "value", "type": "value" } ], "outputsExpiredAt": 1, "position": 1, "priority": 1, "progress": { "detail": { "elapsedMs": 1, "max": 1, "nodeId": "value", "ratio": 1, "source": "comfy_progress", "timeoutMs": 1, "value": 1 }, "etaMs": 1, "percent": 1, "phase": "queued", "updatedAt": 1 }, "prompt": "value", "promptControl": { "enabled": true, "mode": "manual", "source": "explicit" }, "publishedOutputs": [ "value" ], "queueEtaMs": 1, "rfShift": 1, "role": "value", "safety": { "error": "value", "outputs": {}, "reason": "value", "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "seed": 1, "status": "queued", "steps": 1, "storage": { "errors": [ { "error": "value", "path": "value" } ], "status": "value", "storedAt": 1 }, "taggerTags": [ "value" ], "tags": [ "value" ], "updatedAt": 1, "upscaleModelName": "value", "upscaleProfiles": [ { "denoise": 1, "modelName": "value" } ], "upscaleTargetHeight": 1, "upscaleTargetWidth": 1, "userId": 1, "vaeName": "value", "weight": 1, "width": 1 } ], "nextCursor": "value" }, "schema": { "$ref": "#/components/schemas/GeneratorJobListResponse" } } }, "description": "Paginated job list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List your generator jobs", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/jobs' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/jobs',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create an image-generation job from validated parameters, caller-visible models, and caller-owned source uploads.", "operationId": "createGeneratorJob", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "adetailerDetectionOrder": "value", "adetailerNegative": "value", "adetailerPositive": "value", "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cfg": 1, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "modelName": "value", "start": 1, "strength": 1 } ], "denoise": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "imagePath": "value", "loraName": "value", "loras": [ "value" ], "metadata": {}, "mode": "txt2img", "modelName": "value", "negativePrompt": "value", "presetId": 1, "prompt": "value", "promptControl": true, "retentionDays": 1, "rfShift": 1, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "schedulerName": "value", "seed": 1, "sfwMode": true, "steps": 1, "tags": [ "value" ], "upscaleProfiles": [ { "denoise": 1, "model": "value", "modelName": "value", "upscaleModelName": "value" } ], "vaeName": "value", "width": 1 }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "adetailer": { "$ref": "#/components/schemas/GeneratorAdetailerConfig" }, "adetailerDetectionOrder": { "deprecated": true, "description": "Deprecated compatibility alias for `adetailer.detectionOrder`.", "type": "string" }, "adetailerNegative": { "deprecated": true, "description": "Deprecated compatibility alias for `adetailer.negativePrompt`.", "type": "string" }, "adetailerPositive": { "deprecated": true, "description": "Deprecated compatibility alias for `adetailer.positivePrompt`.", "type": "string" }, "attentionCouple": { "description": "Regional prompt payload (max 2 regions).\nUI clients typically derive prompts from `[R1]/[R2]` or `left || right` syntax and auto-generate masks.\nThe parser also accepts exactly two non-empty prompt lines (`line1\\nline2`) as region prompts.\nAPI clients must still provide explicit `maskPath` values.\nADetailer normalization during regional prompts is controlled by `adetailer.attentionCouplePolicy`.\nDefault policy is `strict-face-bbox` for lower cross-region face bleed.\nDuring regional prompts, backend keeps ADetailer split-wildcard prompt modes (`[SEP]`) with normalized wildcard ordering.\nFor `adetailer.positivePrompt`, backend canonicalizes `left || right`, two-line splits (`left\\nright`),\nand `[R1] ... [R2] ...` into `left [SEP] right`.\nIf `adetailer.positivePrompt` is omitted, backend may derive a split detailer prompt from the region prompts.\nIn strict mode, backend forwards regional masks to ADetailer for per-region crop clamping.\n", "properties": { "enabled": { "description": "Whether enabled applies to this attention couple.", "type": "boolean" }, "globalPromptWeight": { "default": 0.01, "description": "Numeric global prompt weight reported for this attention couple. Minimum: 0.01. Maximum: 1.", "maximum": 1, "minimum": 0.01, "type": "number" }, "regions": { "description": "Ordered regions entries included with this attention couple; an empty list means none are available.", "items": { "description": "Structured regions item details for this regions.", "properties": { "maskPath": { "description": "Relative staging path (`generator/...`) to a PNG mask with an alpha channel.\nThe alpha channel must include both transparent and opaque pixels.\nRGB-only masks are rejected.\n", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this regions item; availability depends on visibility and privacy rules.", "type": "string" }, "weight": { "description": "Numeric weight reported for this regions item. Minimum: 0.01. Maximum: 1.", "maximum": 1, "minimum": 0.01, "type": "number" } }, "required": [ "prompt", "maskPath" ], "type": "object" }, "maxItems": 2, "type": "array" } }, "type": "object" }, "batchSize": { "description": "`txt2img` only.\nMust be `1` when upscale/hires is enabled.\n", "type": "integer" }, "cfg": { "description": "Numeric cfg reported for this request payload.", "type": "number" }, "controlnets": { "description": "ControlNet stack (server-enforced max count; currently defaults to 2).", "items": { "description": "Structured controlnets item details for this controlnets.", "properties": { "end": { "description": "Numeric end reported for this controlnets item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "imagePath": { "description": "Server-provided path for the image path associated with this controlnets item; treat it as opaque.", "type": "string" }, "model": { "description": "Model associated with this controlnets item; preserve server-returned values when passing them to another operation.", "type": "string" }, "modelName": { "description": "Compatibility alias for `model`.", "type": "string" }, "start": { "description": "Numeric start reported for this controlnets item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "strength": { "description": "Numeric strength reported for this controlnets item. Minimum: 0. Maximum: 2.", "maximum": 2, "minimum": 0, "type": "number" } }, "type": "object" }, "type": "array" }, "denoise": { "description": "Numeric denoise reported for this request payload.", "type": "number" }, "extraSeed": { "description": "A1111-like secondary seed (subseed equivalent) used for noise variation.", "oneOf": [ { "description": "Numeric extra seed reported for this request payload.", "type": "integer" }, { "description": "Extra Seed associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "extraSeedStrength": { "description": "Noise blend factor for `extraSeed` (0 = base noise, 1 = extra-seed noise).\nDefaults to `0.15` when `extraSeed` is provided.\n", "maximum": 1, "minimum": 0, "type": "number" }, "height": { "description": "Numeric height reported for this request payload.", "type": "integer" }, "imagePath": { "description": "Required for img2img/inpaint.\nMust reference an existing upload under `uploads/generator` (relative path `generator/...`).\n", "type": "string" }, "loraName": { "description": "Legacy single-LoRA alias. Prefer `loras`.", "type": "string" }, "loras": { "description": "Ordered loras entries included with this request payload; an empty list means none are available.", "items": { "description": "Loras item associated with this loras; preserve server-returned values when passing them to another operation.", "oneOf": [ { "description": "Loras item associated with this loras; preserve server-returned values when passing them to another operation.", "type": "string" }, { "description": "Structured loras item details for this loras.", "properties": { "name": { "description": "Human-readable name for this loras item; it is not a stable identifier.", "type": "string" }, "weight": { "description": "Numeric weight reported for this loras item.", "type": "number" } }, "type": "object" } ] }, "maxItems": 4, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Structured metadata details for this request payload.", "nullable": true, "type": "object" }, "mode": { "description": "Mode associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `txt2img`, `img2img`, `inpaint`.", "enum": [ "txt2img", "img2img", "inpaint" ], "type": "string" }, "modelName": { "description": "Exact checkpoint name (for example from `GET /api/generator/options` -> `models.checkpoints`).\nDo not send `displayName` or `modelTitle` here.\n", "type": "string" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "presetId": { "description": "Stable identifier for the preset; use it in subsequent API calls instead of a display name.", "type": "integer" }, "prompt": { "description": "Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "promptControl": { "description": "Enables ComfyUI Prompt Control scheduling and alternates, for example `[red hair:blue hair:0.5]`.\nIf omitted, the backend auto-enables Prompt Control when clear schedule syntax is detected.\nSend `false` or `{ \"mode\": \"disabled\" }` to force plain prompt encoding.\nUnsupported Prompt Control model/wildcard/NODE syntax is rejected.\n", "oneOf": [ { "description": "Whether prompt control applies to this request payload.", "type": "boolean" }, { "description": "Prompt Control associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `auto`, `true`, `false`.", "enum": [ "auto", true, false ], "type": "string" }, { "description": "Structured prompt control details for this request payload.", "properties": { "enabled": { "description": "Whether enabled applies to this prompt control.", "type": "boolean" }, "mode": { "description": "Mode associated with this prompt control; preserve server-returned values when passing them to another operation. Supported values: `auto`, `manual`, `disabled`.", "enum": [ "auto", "manual", "disabled" ], "type": "string" } }, "type": "object" } ] }, "retentionDays": { "description": "Numeric retention days reported for this request payload.", "type": "integer" }, "rfShift": { "description": "Numeric rf shift reported for this request payload. Minimum: 1. Maximum: 15.", "maximum": 15, "minimum": 1, "type": "number" }, "samplerName": { "description": "Human-readable sampler name for this request payload; it is not a stable identifier.", "type": "string" }, "scaleFactor": { "description": "Upscale target factor. Applied only when `upscaleProfiles` (or legacy `upscaleModelName`) is set; otherwise treated as `1`.", "type": "number" }, "scheduler": { "description": "Scheduler associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "schedulerName": { "deprecated": true, "description": "Compatibility alias for `scheduler`.", "type": "string" }, "seed": { "description": "Primary seed. `-1` requests randomization.\nIf omitted, the backend also randomizes by default.\n", "oneOf": [ { "description": "Numeric seed reported for this request payload.", "type": "integer" }, { "description": "Seed associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "sfwMode": { "description": "Whether sfw mode applies to this request payload.", "type": "boolean" }, "steps": { "description": "Numeric steps reported for this request payload.", "type": "integer" }, "tags": { "description": "Ordered tags entries included with this request payload; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "upscaleProfiles": { "description": "Upscale pipeline passes (server-enforced max count; currently defaults to 3).", "items": { "description": "Structured upscale profiles item details for this upscale profiles.", "properties": { "denoise": { "description": "Denoise strength for the refinement pass. x4 upscalers require a target `scaleFactor`.", "maximum": 1, "minimum": 0, "type": "number" }, "model": { "description": "Compatibility alias for `modelName`.", "type": "string" }, "modelName": { "description": "Human-readable model name for this upscale profiles item; it is not a stable identifier.", "type": "string" }, "upscaleModelName": { "description": "Compatibility alias for `modelName`.", "type": "string" } }, "type": "object" }, "type": "array" }, "vaeName": { "description": "Human-readable vae name for this request payload; it is not a stable identifier.", "type": "string" }, "width": { "description": "Numeric width reported for this request payload.", "type": "integer" } }, "required": [ "prompt" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "job": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "attempts": 1, "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cancelled": true, "cfg": 1, "comfy": { "messages": [ {} ], "nodeErrors": [ {} ], "status": "value" }, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "start": 1, "strength": 1 } ], "createdAt": 1, "deletedAt": 1, "deletedByUserId": 1, "denoise": 1, "diagnostics": { "adetailer": {}, "adetailerBridge": { "failed": true, "reason": "value", "updatedAt": 1 }, "attentionCouple": {}, "historyTimeoutMs": 1, "workflowCaptured": true }, "error": "value", "expiresAt": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "id": "value", "imagePath": "value", "loraName": "value", "loras": [ { "name": "value", "weight": 1 } ], "metadata": {}, "mode": "txt2img", "modelCapabilities": [ "value" ], "modelName": "value", "negativePrompt": "value", "outputToken": "value", "outputs": [ { "filename": "value", "subfolder": "value", "type": "value" } ], "outputsExpiredAt": 1, "position": 1, "priority": 1, "progress": { "detail": { "elapsedMs": 1, "max": 1, "nodeId": "value", "ratio": 1, "source": "comfy_progress", "timeoutMs": 1, "value": 1 }, "etaMs": 1, "percent": 1, "phase": "queued", "updatedAt": 1 }, "prompt": "value", "promptControl": { "enabled": true, "mode": "manual", "source": "explicit" }, "publishedOutputs": [ "value" ], "queueEtaMs": 1, "rfShift": 1, "role": "value", "safety": { "error": "value", "outputs": {}, "reason": "value", "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "seed": 1, "status": "queued", "steps": 1, "storage": { "errors": [ { "error": "value", "path": "value" } ], "status": "value", "storedAt": 1 }, "taggerTags": [ "value" ], "tags": [ "value" ], "updatedAt": 1, "upscaleModelName": "value", "upscaleProfiles": [ { "denoise": 1, "modelName": "value" } ], "upscaleTargetHeight": 1, "upscaleTargetWidth": 1, "userId": 1, "vaeName": "value", "weight": 1, "width": 1 }, "position": 1, "queueEtaMs": 1 }, "schema": { "$ref": "#/components/schemas/GeneratorJobEnvelope" } } }, "description": "Job queued.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "content": { "application/json": { "example": { "error": "value", "errorCode": "value", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Invalid payload (range checks, unknown model, invalid mode/paths, etc.).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "User banned or restricted by policy.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "User/preset not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "Daily/pending/budget limits exceeded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Generator is disabled (maintenance mode). The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Queue a new generator job", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/jobs' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"presetId\":1,\"mode\":\"txt2img\",\"prompt\":\"value\",\"negativePrompt\":\"value\",\"modelName\":\"value\",\"loras\":[\"value\"],\"loraName\":\"value\",\"vaeName\":\"value\",\"imagePath\":\"value\",\"seed\":1,\"extraSeed\":1,\"extraSeedStrength\":1,\"rfShift\":1,\"steps\":1,\"cfg\":1,\"samplerName\":\"value\",\"scheduler\":\"value\",\"schedulerName\":\"value\",\"width\":1,\"height\":1,\"denoise\":1,\"scaleFactor\":1,\"batchSize\":1,\"retentionDays\":1,\"tags\":[\"value\"],\"sfwMode\":true,\"controlnets\":[{\"model\":\"value\",\"modelName\":\"value\",\"imagePath\":\"value\",\"strength\":1,\"start\":1,\"end\":1}],\"adetailer\":{\"enabled\":true,\"model\":\"value\",\"detector\":\"value\",\"maskMode\":\"segmentation\",\"attentionCouplePolicy\":\"strict-face-bbox\",\"adetailerAttentionCouplePolicy\":\"value\",\"adetailerMaskMode\":\"value\",\"confidence\":1,\"iou\":1,\"denoise\":0.5,\"adetailerDenoise\":1,\"dilate\":4,\"maskBlur\":4,\"maxDetections\":2,\"dropSize\":1,\"positivePrompt\":\"value\",\"negativePrompt\":\"value\",\"detectionOrder\":\"value\",\"timing\":\"pre-upscale\",\"adetailerTiming\":\"value\"},\"adetailerPositive\":\"value\",\"adetailerNegative\":\"value\",\"adetailerDetectionOrder\":\"value\",\"attentionCouple\":{\"enabled\":true,\"globalPromptWeight\":0.01,\"regions\":[{\"prompt\":\"value\",\"maskPath\":\"value\",\"weight\":1}]},\"promptControl\":true,\"upscaleProfiles\":[{\"modelName\":\"value\",\"model\":\"value\",\"upscaleModelName\":\"value\",\"denoise\":1}],\"metadata\":{}}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"presetId\": 1,\n \"mode\": \"txt2img\",\n \"prompt\": \"value\",\n \"negativePrompt\": \"value\",\n \"modelName\": \"value\",\n \"loras\": [\n \"value\"\n ],\n \"loraName\": \"value\",\n \"vaeName\": \"value\",\n \"imagePath\": \"value\",\n \"seed\": 1,\n \"extraSeed\": 1,\n \"extraSeedStrength\": 1,\n \"rfShift\": 1,\n \"steps\": 1,\n \"cfg\": 1,\n \"samplerName\": \"value\",\n \"scheduler\": \"value\",\n \"schedulerName\": \"value\",\n \"width\": 1,\n \"height\": 1,\n \"denoise\": 1,\n \"scaleFactor\": 1,\n \"batchSize\": 1,\n \"retentionDays\": 1,\n \"tags\": [\n \"value\"\n ],\n \"sfwMode\": true,\n \"controlnets\": [\n {\n \"model\": \"value\",\n \"modelName\": \"value\",\n \"imagePath\": \"value\",\n \"strength\": 1,\n \"start\": 1,\n \"end\": 1\n }\n ],\n \"adetailer\": {\n \"enabled\": true,\n \"model\": \"value\",\n \"detector\": \"value\",\n \"maskMode\": \"segmentation\",\n \"attentionCouplePolicy\": \"strict-face-bbox\",\n \"adetailerAttentionCouplePolicy\": \"value\",\n \"adetailerMaskMode\": \"value\",\n \"confidence\": 1,\n \"iou\": 1,\n \"denoise\": 0.5,\n \"adetailerDenoise\": 1,\n \"dilate\": 4,\n \"maskBlur\": 4,\n \"maxDetections\": 2,\n \"dropSize\": 1,\n \"positivePrompt\": \"value\",\n \"negativePrompt\": \"value\",\n \"detectionOrder\": \"value\",\n \"timing\": \"pre-upscale\",\n \"adetailerTiming\": \"value\"\n },\n \"adetailerPositive\": \"value\",\n \"adetailerNegative\": \"value\",\n \"adetailerDetectionOrder\": \"value\",\n \"attentionCouple\": {\n \"enabled\": true,\n \"globalPromptWeight\": 0.01,\n \"regions\": [\n {\n \"prompt\": \"value\",\n \"maskPath\": \"value\",\n \"weight\": 1\n }\n ]\n },\n \"promptControl\": true,\n \"upscaleProfiles\": [\n {\n \"modelName\": \"value\",\n \"model\": \"value\",\n \"upscaleModelName\": \"value\",\n \"denoise\": 1\n }\n ],\n \"metadata\": {}\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/jobs',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"presetId\\\":1,\\\"mode\\\":\\\"txt2img\\\",\\\"prompt\\\":\\\"value\\\",\\\"negativePrompt\\\":\\\"value\\\",\\\"modelName\\\":\\\"value\\\",\\\"loras\\\":[\\\"value\\\"],\\\"loraName\\\":\\\"value\\\",\\\"vaeName\\\":\\\"value\\\",\\\"imagePath\\\":\\\"value\\\",\\\"seed\\\":1,\\\"extraSeed\\\":1,\\\"extraSeedStrength\\\":1,\\\"rfShift\\\":1,\\\"steps\\\":1,\\\"cfg\\\":1,\\\"samplerName\\\":\\\"value\\\",\\\"scheduler\\\":\\\"value\\\",\\\"schedulerName\\\":\\\"value\\\",\\\"width\\\":1,\\\"height\\\":1,\\\"denoise\\\":1,\\\"scaleFactor\\\":1,\\\"batchSize\\\":1,\\\"retentionDays\\\":1,\\\"tags\\\":[\\\"value\\\"],\\\"sfwMode\\\":true,\\\"controlnets\\\":[{\\\"model\\\":\\\"value\\\",\\\"modelName\\\":\\\"value\\\",\\\"imagePath\\\":\\\"value\\\",\\\"strength\\\":1,\\\"start\\\":1,\\\"end\\\":1}],\\\"adetailer\\\":{\\\"enabled\\\":true,\\\"model\\\":\\\"value\\\",\\\"detector\\\":\\\"value\\\",\\\"maskMode\\\":\\\"segmentation\\\",\\\"attentionCouplePolicy\\\":\\\"strict-face-bbox\\\",\\\"adetailerAttentionCouplePolicy\\\":\\\"value\\\",\\\"adetailerMaskMode\\\":\\\"value\\\",\\\"confidence\\\":1,\\\"iou\\\":1,\\\"denoise\\\":0.5,\\\"adetailerDenoise\\\":1,\\\"dilate\\\":4,\\\"maskBlur\\\":4,\\\"maxDetections\\\":2,\\\"dropSize\\\":1,\\\"positivePrompt\\\":\\\"value\\\",\\\"negativePrompt\\\":\\\"value\\\",\\\"detectionOrder\\\":\\\"value\\\",\\\"timing\\\":\\\"pre-upscale\\\",\\\"adetailerTiming\\\":\\\"value\\\"},\\\"adetailerPositive\\\":\\\"value\\\",\\\"adetailerNegative\\\":\\\"value\\\",\\\"adetailerDetectionOrder\\\":\\\"value\\\",\\\"attentionCouple\\\":{\\\"enabled\\\":true,\\\"globalPromptWeight\\\":0.01,\\\"regions\\\":[{\\\"prompt\\\":\\\"value\\\",\\\"maskPath\\\":\\\"value\\\",\\\"weight\\\":1}]},\\\"promptControl\\\":true,\\\"upscaleProfiles\\\":[{\\\"modelName\\\":\\\"value\\\",\\\"model\\\":\\\"value\\\",\\\"upscaleModelName\\\":\\\"value\\\",\\\"denoise\\\":1}],\\\"metadata\\\":{}}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/generator/jobs/bulk-download": { "post": { "description": "Stream a ZIP archive for a bounded set of completed caller-owned image-generation jobs.", "operationId": "downloadGeneratorJobsBulk", "parameters": [ { "description": "Optional comma-separated job id list.\nUse this or request body `ids`.\n", "example": "example-ids", "in": "query", "name": "ids", "schema": { "description": "Ids value documented for this operation.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "ids": [ "value" ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "ids": { "description": "Ordered ids entries included with this request payload; an empty list means none are available.", "items": { "description": "Ids item associated with this ids; preserve server-returned values when passing them to another operation.", "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "ids" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": false }, "responses": { "200": { "content": { "application/zip": { "schema": { "description": "200 response for api generator jobs bulk download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Zip stream containing selected outputs.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid ids payload or too many jobs requested.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "content": { "application/json": { "examples": { "sfwRestricted": { "value": { "error": "SFW mode enabled: image appears unsafe.", "errorCode": "GENERATOR_OUTPUT_UNSAFE_SFW", "safetyReason": "nsfw", "safetyStatus": "quarantined" } } }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Safety restriction blocks download.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "No matching jobs/outputs found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Failed to build download archive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download multiple jobs as one zip archive", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/jobs/bulk-download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"ids\":[\"value\"]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/bulk-download', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"ids\": [\n \"value\"\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/jobs/bulk-download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"ids\\\":[\\\"value\\\"]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/jobs/compare": { "post": { "description": "Create a bounded image-generation comparison run across the requested axes and return its caller-owned jobs.", "operationId": "createGeneratorCompareRun", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "adetailerDetectionOrder": "value", "adetailerNegative": "value", "adetailerPositive": "value", "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cfg": 1, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "modelName": "value", "start": 1, "strength": 1 } ], "denoise": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "loraName": "value", "loras": [ "value" ], "metadata": {}, "mode": "txt2img", "modelName": "value", "modelNames": [ "value", "value" ], "negativePrompt": "value", "presetId": 1, "prompt": "value", "promptControl": true, "retentionDays": 1, "rfShift": 1, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "schedulerName": "value", "seed": 1, "sfwMode": true, "steps": 1, "tags": [ "value" ], "upscaleProfiles": [ { "denoise": 1, "model": "value", "modelName": "value", "upscaleModelName": "value" } ], "vaeName": "value", "width": 1 }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "adetailer": { "$ref": "#/components/schemas/GeneratorAdetailerConfig" }, "adetailerDetectionOrder": { "deprecated": true, "description": "Deprecated compatibility alias for `adetailer.detectionOrder`.", "type": "string" }, "adetailerNegative": { "deprecated": true, "description": "Deprecated compatibility alias for `adetailer.negativePrompt`.", "type": "string" }, "adetailerPositive": { "deprecated": true, "description": "Deprecated compatibility alias for `adetailer.positivePrompt`.", "type": "string" }, "attentionCouple": { "description": "Regional prompt payload. API clients must provide explicit `maskPath` values.", "properties": { "enabled": { "description": "Whether enabled applies to this attention couple.", "type": "boolean" }, "globalPromptWeight": { "default": 0.01, "description": "Numeric global prompt weight reported for this attention couple. Minimum: 0.01. Maximum: 1.", "maximum": 1, "minimum": 0.01, "type": "number" }, "regions": { "description": "Ordered regions entries included with this attention couple; an empty list means none are available.", "items": { "description": "Structured regions item details for this regions.", "properties": { "maskPath": { "description": "Relative staging path (`generator/...`) to a PNG mask with an alpha channel.", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this regions item; availability depends on visibility and privacy rules.", "type": "string" }, "weight": { "description": "Numeric weight reported for this regions item. Minimum: 0.01. Maximum: 1.", "maximum": 1, "minimum": 0.01, "type": "number" } }, "required": [ "prompt", "maskPath" ], "type": "object" }, "maxItems": 2, "type": "array" } }, "type": "object" }, "batchSize": { "description": "Compare always queues each target as one output; non-1 values are normalized to 1.", "enum": [ 1 ], "type": "integer" }, "cfg": { "description": "Numeric cfg reported for this request payload.", "type": "number" }, "controlnets": { "description": "ControlNet stack, validated once per target before any compare job is queued.", "items": { "description": "Structured controlnets item details for this controlnets.", "properties": { "end": { "description": "Numeric end reported for this controlnets item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "imagePath": { "description": "Server-provided path for the image path associated with this controlnets item; treat it as opaque.", "type": "string" }, "model": { "description": "Model associated with this controlnets item; preserve server-returned values when passing them to another operation.", "type": "string" }, "modelName": { "description": "Compatibility alias for `model`.", "type": "string" }, "start": { "description": "Numeric start reported for this controlnets item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "strength": { "description": "Numeric strength reported for this controlnets item. Minimum: 0. Maximum: 2.", "maximum": 2, "minimum": 0, "type": "number" } }, "type": "object" }, "type": "array" }, "denoise": { "description": "Numeric denoise reported for this request payload.", "type": "number" }, "extraSeed": { "description": "A1111-like secondary seed (subseed equivalent) used for noise variation.", "oneOf": [ { "description": "Numeric extra seed reported for this request payload.", "type": "integer" }, { "description": "Extra Seed associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "extraSeedStrength": { "description": "Numeric extra seed strength reported for this request payload. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "height": { "description": "Numeric height reported for this request payload.", "type": "integer" }, "loraName": { "description": "Legacy single-LoRA alias. Prefer `loras`.", "type": "string" }, "loras": { "description": "Ordered loras entries included with this request payload; an empty list means none are available.", "items": { "description": "Loras item associated with this loras; preserve server-returned values when passing them to another operation.", "oneOf": [ { "description": "Loras item associated with this loras; preserve server-returned values when passing them to another operation.", "type": "string" }, { "description": "Structured loras item details for this loras.", "properties": { "name": { "description": "Human-readable name for this loras item; it is not a stable identifier.", "type": "string" }, "weight": { "description": "Numeric weight reported for this loras item.", "type": "number" } }, "type": "object" } ] }, "maxItems": 4, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Structured metadata details for this request payload.", "nullable": true, "type": "object" }, "mode": { "description": "Mode associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `txt2img`.", "enum": [ "txt2img" ], "type": "string" }, "modelName": { "deprecated": true, "description": "Ignored for compare requests; use `modelNames`.", "type": "string" }, "modelNames": { "description": "Exact checkpoint names. Duplicate names are rejected.", "items": { "description": "Model Names item associated with this model names; preserve server-returned values when passing them to another operation.", "type": "string" }, "maxItems": 4, "minItems": 2, "type": "array" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "presetId": { "description": "Stable identifier for the preset; use it in subsequent API calls instead of a display name.", "type": "integer" }, "prompt": { "description": "Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "promptControl": { "description": "Enables ComfyUI Prompt Control scheduling and alternates.", "oneOf": [ { "description": "Whether prompt control applies to this request payload.", "type": "boolean" }, { "description": "Prompt Control associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `auto`, `true`, `false`.", "enum": [ "auto", true, false ], "type": "string" }, { "description": "Structured prompt control details for this request payload.", "properties": { "enabled": { "description": "Whether enabled applies to this prompt control.", "type": "boolean" }, "mode": { "description": "Mode associated with this prompt control; preserve server-returned values when passing them to another operation. Supported values: `auto`, `manual`, `disabled`.", "enum": [ "auto", "manual", "disabled" ], "type": "string" } }, "type": "object" } ] }, "retentionDays": { "description": "Numeric retention days reported for this request payload.", "type": "integer" }, "rfShift": { "description": "Numeric rf shift reported for this request payload. Minimum: 1. Maximum: 15.", "maximum": 15, "minimum": 1, "type": "number" }, "samplerName": { "description": "Human-readable sampler name for this request payload; it is not a stable identifier.", "type": "string" }, "scaleFactor": { "description": "Upscale target factor. Applied only when `upscaleProfiles` or legacy `upscaleModelName` is set.", "type": "number" }, "scheduler": { "description": "Scheduler associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "schedulerName": { "deprecated": true, "description": "Compatibility alias for `scheduler`.", "type": "string" }, "seed": { "description": "Shared seed. Omit or send `-1` to randomize once for the whole compare run.", "oneOf": [ { "description": "Numeric seed reported for this request payload.", "type": "integer" }, { "description": "Seed associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" } ] }, "sfwMode": { "description": "Whether sfw mode applies to this request payload.", "type": "boolean" }, "steps": { "description": "Numeric steps reported for this request payload.", "type": "integer" }, "tags": { "description": "Ordered tags entries included with this request payload; an empty list means none are available.", "items": { "description": "Tags item associated with this tags; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "upscaleProfiles": { "description": "Upscale pipeline passes, applied independently to every compare target.", "items": { "description": "Structured upscale profiles item details for this upscale profiles.", "properties": { "denoise": { "description": "Numeric denoise reported for this upscale profiles item. Minimum: 0. Maximum: 1.", "maximum": 1, "minimum": 0, "type": "number" }, "model": { "description": "Compatibility alias for `modelName`.", "type": "string" }, "modelName": { "description": "Human-readable model name for this upscale profiles item; it is not a stable identifier.", "type": "string" }, "upscaleModelName": { "description": "Compatibility alias for `modelName`.", "type": "string" } }, "type": "object" }, "type": "array" }, "vaeName": { "description": "Human-readable vae name for this request payload; it is not a stable identifier.", "type": "string" }, "width": { "description": "Numeric width reported for this request payload.", "type": "integer" } }, "required": [ "prompt", "modelNames" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "compareRun": { "completedCount": 1, "cost": { "budgetProfile": "value", "dailyUsage": 1, "estimatedGpuMs": 1, "estimatedVramMb": 1, "jobs": 1, "queueSlots": 1, "weight": 1 }, "count": 1, "createdAt": 1, "failedCount": 1, "grid": { "downloadUrl": "value", "height": 1, "previewHeight": 1, "previewRelativePath": "value", "previewUpdatedAt": 1, "previewWidth": 1, "reason": "value", "relativePath": "value", "status": "pending", "updatedAt": 1, "url": "value", "width": 1 }, "id": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "modelNames": [ "value" ], "pendingCount": 1, "seed": 1, "status": "queued", "updatedAt": 1 }, "jobs": [ { "job": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "attempts": 1, "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cancelled": true, "cfg": 1, "comfy": { "messages": [ {} ], "nodeErrors": [ {} ], "status": "value" }, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "start": 1, "strength": 1 } ], "createdAt": 1, "deletedAt": 1, "deletedByUserId": 1, "denoise": 1, "diagnostics": { "adetailer": {}, "adetailerBridge": { "failed": true, "reason": "value", "updatedAt": 1 }, "attentionCouple": {}, "historyTimeoutMs": 1, "workflowCaptured": true }, "error": "value", "expiresAt": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "id": "value", "imagePath": "value", "loraName": "value", "loras": [ { "name": "value", "weight": 1 } ], "metadata": {}, "mode": "txt2img", "modelCapabilities": [ "value" ], "modelName": "value", "negativePrompt": "value", "outputToken": "value", "outputs": [ { "filename": "value", "subfolder": "value", "type": "value" } ], "outputsExpiredAt": 1, "position": 1, "priority": 1, "progress": { "detail": { "elapsedMs": 1, "max": 1, "nodeId": "value", "ratio": 1, "source": "comfy_progress", "timeoutMs": 1, "value": 1 }, "etaMs": 1, "percent": 1, "phase": "queued", "updatedAt": 1 }, "prompt": "value", "promptControl": { "enabled": true, "mode": "manual", "source": "explicit" }, "publishedOutputs": [ "value" ], "queueEtaMs": 1, "rfShift": 1, "role": "value", "safety": { "error": "value", "outputs": {}, "reason": "value", "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "seed": 1, "status": "queued", "steps": 1, "storage": { "errors": [ { "error": "value", "path": "value" } ], "status": "value", "storedAt": 1 }, "taggerTags": [ "value" ], "tags": [ "value" ], "updatedAt": 1, "upscaleModelName": "value", "upscaleProfiles": [ { "denoise": 1, "modelName": "value" } ], "upscaleTargetHeight": 1, "upscaleTargetWidth": 1, "userId": 1, "vaeName": "value", "weight": 1, "width": 1 }, "position": 1, "queueEtaMs": 1 } ] }, "schema": { "$ref": "#/components/schemas/GeneratorCompareResponse" } } }, "description": "Compare jobs queued.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "content": { "application/json": { "example": { "error": "value", "errorCode": "value", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Invalid payload, target count, mode, duplicate target, or incompatible LoRA/base family.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "User banned or restricted by policy.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "User/preset not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "Daily/pending/budget limits exceeded for the aggregate run.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Generator is disabled (maintenance mode). The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Queue one txt2img prompt across multiple checkpoints", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/jobs/compare' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"prompt\":\"value\",\"mode\":\"txt2img\",\"presetId\":1,\"modelName\":\"value\",\"modelNames\":[\"value\",\"value\"],\"seed\":1,\"negativePrompt\":\"value\",\"loras\":[\"value\"],\"loraName\":\"value\",\"vaeName\":\"value\",\"extraSeed\":1,\"extraSeedStrength\":1,\"rfShift\":1,\"samplerName\":\"value\",\"scheduler\":\"value\",\"schedulerName\":\"value\",\"width\":1,\"height\":1,\"steps\":1,\"cfg\":1,\"denoise\":1,\"scaleFactor\":1,\"batchSize\":1,\"retentionDays\":1,\"tags\":[\"value\"],\"sfwMode\":true,\"controlnets\":[{\"model\":\"value\",\"modelName\":\"value\",\"imagePath\":\"value\",\"strength\":1,\"start\":1,\"end\":1}],\"adetailer\":{\"enabled\":true,\"model\":\"value\",\"detector\":\"value\",\"maskMode\":\"segmentation\",\"attentionCouplePolicy\":\"strict-face-bbox\",\"adetailerAttentionCouplePolicy\":\"value\",\"adetailerMaskMode\":\"value\",\"confidence\":1,\"iou\":1,\"denoise\":0.5,\"adetailerDenoise\":1,\"dilate\":4,\"maskBlur\":4,\"maxDetections\":2,\"dropSize\":1,\"positivePrompt\":\"value\",\"negativePrompt\":\"value\",\"detectionOrder\":\"value\",\"timing\":\"pre-upscale\",\"adetailerTiming\":\"value\"},\"adetailerPositive\":\"value\",\"adetailerNegative\":\"value\",\"adetailerDetectionOrder\":\"value\",\"attentionCouple\":{\"enabled\":true,\"globalPromptWeight\":0.01,\"regions\":[{\"prompt\":\"value\",\"maskPath\":\"value\",\"weight\":1}]},\"promptControl\":true,\"upscaleProfiles\":[{\"modelName\":\"value\",\"model\":\"value\",\"upscaleModelName\":\"value\",\"denoise\":1}],\"metadata\":{}}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/compare', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"prompt\": \"value\",\n \"mode\": \"txt2img\",\n \"presetId\": 1,\n \"modelName\": \"value\",\n \"modelNames\": [\n \"value\",\n \"value\"\n ],\n \"seed\": 1,\n \"negativePrompt\": \"value\",\n \"loras\": [\n \"value\"\n ],\n \"loraName\": \"value\",\n \"vaeName\": \"value\",\n \"extraSeed\": 1,\n \"extraSeedStrength\": 1,\n \"rfShift\": 1,\n \"samplerName\": \"value\",\n \"scheduler\": \"value\",\n \"schedulerName\": \"value\",\n \"width\": 1,\n \"height\": 1,\n \"steps\": 1,\n \"cfg\": 1,\n \"denoise\": 1,\n \"scaleFactor\": 1,\n \"batchSize\": 1,\n \"retentionDays\": 1,\n \"tags\": [\n \"value\"\n ],\n \"sfwMode\": true,\n \"controlnets\": [\n {\n \"model\": \"value\",\n \"modelName\": \"value\",\n \"imagePath\": \"value\",\n \"strength\": 1,\n \"start\": 1,\n \"end\": 1\n }\n ],\n \"adetailer\": {\n \"enabled\": true,\n \"model\": \"value\",\n \"detector\": \"value\",\n \"maskMode\": \"segmentation\",\n \"attentionCouplePolicy\": \"strict-face-bbox\",\n \"adetailerAttentionCouplePolicy\": \"value\",\n \"adetailerMaskMode\": \"value\",\n \"confidence\": 1,\n \"iou\": 1,\n \"denoise\": 0.5,\n \"adetailerDenoise\": 1,\n \"dilate\": 4,\n \"maskBlur\": 4,\n \"maxDetections\": 2,\n \"dropSize\": 1,\n \"positivePrompt\": \"value\",\n \"negativePrompt\": \"value\",\n \"detectionOrder\": \"value\",\n \"timing\": \"pre-upscale\",\n \"adetailerTiming\": \"value\"\n },\n \"adetailerPositive\": \"value\",\n \"adetailerNegative\": \"value\",\n \"adetailerDetectionOrder\": \"value\",\n \"attentionCouple\": {\n \"enabled\": true,\n \"globalPromptWeight\": 0.01,\n \"regions\": [\n {\n \"prompt\": \"value\",\n \"maskPath\": \"value\",\n \"weight\": 1\n }\n ]\n },\n \"promptControl\": true,\n \"upscaleProfiles\": [\n {\n \"modelName\": \"value\",\n \"model\": \"value\",\n \"upscaleModelName\": \"value\",\n \"denoise\": 1\n }\n ],\n \"metadata\": {}\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/jobs/compare',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"prompt\\\":\\\"value\\\",\\\"mode\\\":\\\"txt2img\\\",\\\"presetId\\\":1,\\\"modelName\\\":\\\"value\\\",\\\"modelNames\\\":[\\\"value\\\",\\\"value\\\"],\\\"seed\\\":1,\\\"negativePrompt\\\":\\\"value\\\",\\\"loras\\\":[\\\"value\\\"],\\\"loraName\\\":\\\"value\\\",\\\"vaeName\\\":\\\"value\\\",\\\"extraSeed\\\":1,\\\"extraSeedStrength\\\":1,\\\"rfShift\\\":1,\\\"samplerName\\\":\\\"value\\\",\\\"scheduler\\\":\\\"value\\\",\\\"schedulerName\\\":\\\"value\\\",\\\"width\\\":1,\\\"height\\\":1,\\\"steps\\\":1,\\\"cfg\\\":1,\\\"denoise\\\":1,\\\"scaleFactor\\\":1,\\\"batchSize\\\":1,\\\"retentionDays\\\":1,\\\"tags\\\":[\\\"value\\\"],\\\"sfwMode\\\":true,\\\"controlnets\\\":[{\\\"model\\\":\\\"value\\\",\\\"modelName\\\":\\\"value\\\",\\\"imagePath\\\":\\\"value\\\",\\\"strength\\\":1,\\\"start\\\":1,\\\"end\\\":1}],\\\"adetailer\\\":{\\\"enabled\\\":true,\\\"model\\\":\\\"value\\\",\\\"detector\\\":\\\"value\\\",\\\"maskMode\\\":\\\"segmentation\\\",\\\"attentionCouplePolicy\\\":\\\"strict-face-bbox\\\",\\\"adetailerAttentionCouplePolicy\\\":\\\"value\\\",\\\"adetailerMaskMode\\\":\\\"value\\\",\\\"confidence\\\":1,\\\"iou\\\":1,\\\"denoise\\\":0.5,\\\"adetailerDenoise\\\":1,\\\"dilate\\\":4,\\\"maskBlur\\\":4,\\\"maxDetections\\\":2,\\\"dropSize\\\":1,\\\"positivePrompt\\\":\\\"value\\\",\\\"negativePrompt\\\":\\\"value\\\",\\\"detectionOrder\\\":\\\"value\\\",\\\"timing\\\":\\\"pre-upscale\\\",\\\"adetailerTiming\\\":\\\"value\\\"},\\\"adetailerPositive\\\":\\\"value\\\",\\\"adetailerNegative\\\":\\\"value\\\",\\\"adetailerDetectionOrder\\\":\\\"value\\\",\\\"attentionCouple\\\":{\\\"enabled\\\":true,\\\"globalPromptWeight\\\":0.01,\\\"regions\\\":[{\\\"prompt\\\":\\\"value\\\",\\\"maskPath\\\":\\\"value\\\",\\\"weight\\\":1}]},\\\"promptControl\\\":true,\\\"upscaleProfiles\\\":[{\\\"modelName\\\":\\\"value\\\",\\\"model\\\":\\\"value\\\",\\\"upscaleModelName\\\":\\\"value\\\",\\\"denoise\\\":1}],\\\"metadata\\\":{}}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/generator/jobs/{id}": { "delete": { "description": "Delete one caller-owned image-generation job and its managed outputs when runtime state permits. Repeating the request leaves it absent.", "operationId": "deleteGeneratorJob", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing job id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Job not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Running/queued jobs cannot be deleted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Delete failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Soft-delete a finished generator job", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/generator/jobs/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/generator/jobs/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one image-generation job owned by the authenticated caller, including progress, parameters, errors, and output metadata.", "operationId": "getGeneratorJob", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "job": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "attempts": 1, "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cancelled": true, "cfg": 1, "comfy": { "messages": [ {} ], "nodeErrors": [ {} ], "status": "value" }, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "start": 1, "strength": 1 } ], "createdAt": 1, "deletedAt": 1, "deletedByUserId": 1, "denoise": 1, "diagnostics": { "adetailer": {}, "adetailerBridge": { "failed": true, "reason": "value", "updatedAt": 1 }, "attentionCouple": {}, "historyTimeoutMs": 1, "workflowCaptured": true }, "error": "value", "expiresAt": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "id": "value", "imagePath": "value", "loraName": "value", "loras": [ { "name": "value", "weight": 1 } ], "metadata": {}, "mode": "txt2img", "modelCapabilities": [ "value" ], "modelName": "value", "negativePrompt": "value", "outputToken": "value", "outputs": [ { "filename": "value", "subfolder": "value", "type": "value" } ], "outputsExpiredAt": 1, "position": 1, "priority": 1, "progress": { "detail": { "elapsedMs": 1, "max": 1, "nodeId": "value", "ratio": 1, "source": "comfy_progress", "timeoutMs": 1, "value": 1 }, "etaMs": 1, "percent": 1, "phase": "queued", "updatedAt": 1 }, "prompt": "value", "promptControl": { "enabled": true, "mode": "manual", "source": "explicit" }, "publishedOutputs": [ "value" ], "queueEtaMs": 1, "rfShift": 1, "role": "value", "safety": { "error": "value", "outputs": {}, "reason": "value", "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "seed": 1, "status": "queued", "steps": 1, "storage": { "errors": [ { "error": "value", "path": "value" } ], "status": "value", "storedAt": 1 }, "taggerTags": [ "value" ], "tags": [ "value" ], "updatedAt": 1, "upscaleModelName": "value", "upscaleProfiles": [ { "denoise": 1, "modelName": "value" } ], "upscaleTargetHeight": 1, "upscaleTargetWidth": 1, "userId": 1, "vaeName": "value", "weight": 1, "width": 1 }, "position": 1, "queueEtaMs": 1 }, "schema": { "$ref": "#/components/schemas/GeneratorJobEnvelope" } } }, "description": "Job payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Job not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get one generator job", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/jobs/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/jobs/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/jobs/{id}/cancel": { "post": { "description": "Cancel one caller-owned image-generation job when its current state allows cancellation. Repeated calls do not create additional work.", "operationId": "cancelGeneratorJob", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "job": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "attempts": 1, "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cancelled": true, "cfg": 1, "comfy": { "messages": [ {} ], "nodeErrors": [ {} ], "status": "value" }, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "start": 1, "strength": 1 } ], "createdAt": 1, "deletedAt": 1, "deletedByUserId": 1, "denoise": 1, "diagnostics": { "adetailer": {}, "adetailerBridge": { "failed": true, "reason": "value", "updatedAt": 1 }, "attentionCouple": {}, "historyTimeoutMs": 1, "workflowCaptured": true }, "error": "value", "expiresAt": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "id": "value", "imagePath": "value", "loraName": "value", "loras": [ { "name": "value", "weight": 1 } ], "metadata": {}, "mode": "txt2img", "modelCapabilities": [ "value" ], "modelName": "value", "negativePrompt": "value", "outputToken": "value", "outputs": [ { "filename": "value", "subfolder": "value", "type": "value" } ], "outputsExpiredAt": 1, "position": 1, "priority": 1, "progress": { "detail": { "elapsedMs": 1, "max": 1, "nodeId": "value", "ratio": 1, "source": "comfy_progress", "timeoutMs": 1, "value": 1 }, "etaMs": 1, "percent": 1, "phase": "queued", "updatedAt": 1 }, "prompt": "value", "promptControl": { "enabled": true, "mode": "manual", "source": "explicit" }, "publishedOutputs": [ "value" ], "queueEtaMs": 1, "rfShift": 1, "role": "value", "safety": { "error": "value", "outputs": {}, "reason": "value", "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "seed": 1, "status": "queued", "steps": 1, "storage": { "errors": [ { "error": "value", "path": "value" } ], "status": "value", "storedAt": 1 }, "taggerTags": [ "value" ], "tags": [ "value" ], "updatedAt": 1, "upscaleModelName": "value", "upscaleProfiles": [ { "denoise": 1, "modelName": "value" } ], "upscaleTargetHeight": 1, "upscaleTargetWidth": 1, "userId": 1, "vaeName": "value", "weight": 1, "width": 1 }, "position": 1, "queueEtaMs": 1 }, "schema": { "$ref": "#/components/schemas/GeneratorJobEnvelope" } } }, "description": "Cancel request accepted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing job id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Job not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Job is already completed/failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Cancel a queued or running generator job", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/jobs/123/cancel' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/123/cancel', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/jobs/123/cancel',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/generator/jobs/{id}/download": { "get": { "description": "Download the primary image output of a completed caller-owned generation job with integrity and content metadata.", "operationId": "downloadGeneratorJob", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "description": "200 response for api generator jobs id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Zip stream with all job outputs.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "content": { "application/json": { "examples": { "sfwRestricted": { "value": { "error": "SFW mode enabled: image appears unsafe.", "errorCode": "GENERATOR_OUTPUT_UNSAFE_SFW", "safetyReason": "nsfw", "safetyStatus": "quarantined" } } }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Safety restriction blocks download.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Job/output not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Failed to build download archive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download one job as zip", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/jobs/123/download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/123/download', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/jobs/123/download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/jobs/{id}/outputs/{outputId}/download": { "get": { "description": "Download a selected image output of a completed caller-owned generation job with integrity and content metadata.", "operationId": "downloadGeneratorJobOutput", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } }, { "description": "Output selector.\n- `0`, `1`, ...: zero-based index in `job.outputs`\n- URL-encoded relative path from `${subfolder}/${filename}` (example: `nested%2Fleaf.png`)\n- `generator/` prefix is optional (`generator%2Fnested%2Fleaf.png` also works)\n", "examples": { "byIndex": { "value": "0" }, "byRelativePath": { "value": "nested%2Fleaf.png" } }, "in": "path", "name": "outputId", "required": true, "schema": { "description": "Output Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "200 response for api generator jobs id outputs output Id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Binary file stream.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "content": { "application/json": { "examples": { "pendingReview": { "value": { "error": "Outputs are pending review.", "errorCode": "GENERATOR_OUTPUT_PENDING_REVIEW", "safetyReason": null, "safetyStatus": "pending_review" } } }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Safety restriction blocks download.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Job/output not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Failed to download output.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download a single job output file", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/jobs/123/outputs/123/download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/123/outputs/123/download', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/jobs/123/outputs/123/download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/jobs/{id}/publish": { "post": { "description": "Publish a completed caller-owned generator output into the normal image workflow once and return the resulting resource.", "operationId": "publishGeneratorJob", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "outputs": [ "value" ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "outputs": { "description": "Optional subset of output relatives to publish (for example `generator/job-id/file.png`).\nOutput indices are not accepted here.\n", "items": { "description": "Outputs item associated with this outputs; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": false }, "responses": { "201": { "content": { "application/json": { "example": { "alreadyPublished": [ "value" ], "alreadyPublishedCount": 1, "count": 1, "images": [ {} ] }, "schema": { "$ref": "#/components/schemas/GeneratorPublishResponse" } } }, "description": "Outputs published.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Job not completed, invalid output selection, or no outputs.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "content": { "application/json": { "example": { "error": "value", "errorCode": "value", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Missing role or safety restriction.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Job or selected outputs not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Selected outputs already published. The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Publish completed generator outputs to site images", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/jobs/123/publish' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"outputs\":[\"value\"]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/123/publish', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"outputs\": [\n \"value\"\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/jobs/123/publish',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"outputs\\\":[\\\"value\\\"]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/generator/jobs/{id}/remix": { "post": { "description": "Create a new caller-owned image-generation job derived from an accessible source job and explicit parameter overrides.", "operationId": "remixGeneratorJob", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "adetailerDetectionOrder": "value", "adetailerNegative": "value", "adetailerPositive": "value", "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cfg": 1, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "modelName": "value", "start": 1, "strength": 1 } ], "denoise": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "imagePath": "value", "loraName": "value", "loras": [ "value" ], "metadata": {}, "mode": "txt2img", "modelName": "value", "negativePrompt": "value", "presetId": 1, "prompt": "value", "promptControl": true, "retentionDays": 1, "rfShift": 1, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "schedulerName": "value", "seed": 1, "sfwMode": true, "steps": 1, "tags": [ "value" ], "upscaleProfiles": [ { "denoise": 1, "model": "value", "modelName": "value", "upscaleModelName": "value" } ], "vaeName": "value", "width": 1 }, "schema": { "$ref": "#/components/schemas/GeneratorJobRemixRequest" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "job": { "adetailer": { "adetailerAttentionCouplePolicy": "value", "adetailerDenoise": 1, "adetailerMaskMode": "value", "adetailerTiming": "value", "attentionCouplePolicy": "strict-face-bbox", "confidence": 1, "denoise": 0.5, "detectionOrder": "value", "detector": "value", "dilate": 4, "dropSize": 1, "enabled": true, "iou": 1, "maskBlur": 4, "maskMode": "segmentation", "maxDetections": 2, "model": "value", "negativePrompt": "value", "positivePrompt": "value", "timing": "pre-upscale" }, "attempts": 1, "attentionCouple": { "enabled": true, "globalPromptWeight": 0.01, "regions": [ { "maskPath": "value", "prompt": "value", "weight": 1 } ] }, "batchSize": 1, "cancelled": true, "cfg": 1, "comfy": { "messages": [ {} ], "nodeErrors": [ {} ], "status": "value" }, "controlnets": [ { "end": 1, "imagePath": "value", "model": "value", "start": 1, "strength": 1 } ], "createdAt": 1, "deletedAt": 1, "deletedByUserId": 1, "denoise": 1, "diagnostics": { "adetailer": {}, "adetailerBridge": { "failed": true, "reason": "value", "updatedAt": 1 }, "attentionCouple": {}, "historyTimeoutMs": 1, "workflowCaptured": true }, "error": "value", "expiresAt": 1, "extraSeed": 1, "extraSeedStrength": 1, "height": 1, "id": "value", "imagePath": "value", "loraName": "value", "loras": [ { "name": "value", "weight": 1 } ], "metadata": {}, "mode": "txt2img", "modelCapabilities": [ "value" ], "modelName": "value", "negativePrompt": "value", "outputToken": "value", "outputs": [ { "filename": "value", "subfolder": "value", "type": "value" } ], "outputsExpiredAt": 1, "position": 1, "priority": 1, "progress": { "detail": { "elapsedMs": 1, "max": 1, "nodeId": "value", "ratio": 1, "source": "comfy_progress", "timeoutMs": 1, "value": 1 }, "etaMs": 1, "percent": 1, "phase": "queued", "updatedAt": 1 }, "prompt": "value", "promptControl": { "enabled": true, "mode": "manual", "source": "explicit" }, "publishedOutputs": [ "value" ], "queueEtaMs": 1, "rfShift": 1, "role": "value", "safety": { "error": "value", "outputs": {}, "reason": "value", "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scaleFactor": 1, "scheduler": "value", "seed": 1, "status": "queued", "steps": 1, "storage": { "errors": [ { "error": "value", "path": "value" } ], "status": "value", "storedAt": 1 }, "taggerTags": [ "value" ], "tags": [ "value" ], "updatedAt": 1, "upscaleModelName": "value", "upscaleProfiles": [ { "denoise": 1, "modelName": "value" } ], "upscaleTargetHeight": 1, "upscaleTargetWidth": 1, "userId": 1, "vaeName": "value", "weight": 1, "width": 1 }, "position": 1, "queueEtaMs": 1, "remixedFrom": "value" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/GeneratorJobEnvelope" }, { "description": "Fields describing 202 response for api generator jobs id remix in Developer API requests and responses.", "properties": { "remixedFrom": { "description": "Remixed From associated with this 202 response for api generator jobs id remix; preserve server-returned values when passing them to another operation.", "type": "string" } }, "required": [ "remixedFrom" ], "type": "object" } ], "description": "202 response for api generator jobs id remix value documented for this operation." } } }, "description": "Remix job queued.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Access restricted or banned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Source job or user not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "Limit/budget exceeded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Generator is disabled (maintenance mode). The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Queue a new job from an existing one", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/jobs/123/remix' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"prompt\":\"value\",\"mode\":\"txt2img\",\"presetId\":1,\"negativePrompt\":\"value\",\"modelName\":\"value\",\"loras\":[\"value\"],\"loraName\":\"value\",\"vaeName\":\"value\",\"imagePath\":\"value\",\"seed\":1,\"extraSeed\":1,\"extraSeedStrength\":1,\"rfShift\":1,\"steps\":1,\"cfg\":1,\"samplerName\":\"value\",\"scheduler\":\"value\",\"schedulerName\":\"value\",\"width\":1,\"height\":1,\"denoise\":1,\"scaleFactor\":1,\"batchSize\":1,\"promptControl\":true,\"retentionDays\":1,\"tags\":[\"value\"],\"sfwMode\":true,\"controlnets\":[{\"model\":\"value\",\"modelName\":\"value\",\"imagePath\":\"value\",\"strength\":1,\"start\":1,\"end\":1}],\"adetailer\":{\"enabled\":true,\"model\":\"value\",\"detector\":\"value\",\"maskMode\":\"segmentation\",\"attentionCouplePolicy\":\"strict-face-bbox\",\"adetailerAttentionCouplePolicy\":\"value\",\"adetailerMaskMode\":\"value\",\"confidence\":1,\"iou\":1,\"denoise\":0.5,\"adetailerDenoise\":1,\"dilate\":4,\"maskBlur\":4,\"maxDetections\":2,\"dropSize\":1,\"positivePrompt\":\"value\",\"negativePrompt\":\"value\",\"detectionOrder\":\"value\",\"timing\":\"pre-upscale\",\"adetailerTiming\":\"value\"},\"adetailerPositive\":\"value\",\"adetailerNegative\":\"value\",\"adetailerDetectionOrder\":\"value\",\"attentionCouple\":{\"enabled\":true,\"globalPromptWeight\":0.01,\"regions\":[{\"prompt\":\"value\",\"maskPath\":\"value\",\"weight\":1}]},\"upscaleProfiles\":[{\"modelName\":\"value\",\"model\":\"value\",\"upscaleModelName\":\"value\",\"denoise\":1}],\"metadata\":{}}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/jobs/123/remix', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"prompt\": \"value\",\n \"mode\": \"txt2img\",\n \"presetId\": 1,\n \"negativePrompt\": \"value\",\n \"modelName\": \"value\",\n \"loras\": [\n \"value\"\n ],\n \"loraName\": \"value\",\n \"vaeName\": \"value\",\n \"imagePath\": \"value\",\n \"seed\": 1,\n \"extraSeed\": 1,\n \"extraSeedStrength\": 1,\n \"rfShift\": 1,\n \"steps\": 1,\n \"cfg\": 1,\n \"samplerName\": \"value\",\n \"scheduler\": \"value\",\n \"schedulerName\": \"value\",\n \"width\": 1,\n \"height\": 1,\n \"denoise\": 1,\n \"scaleFactor\": 1,\n \"batchSize\": 1,\n \"promptControl\": true,\n \"retentionDays\": 1,\n \"tags\": [\n \"value\"\n ],\n \"sfwMode\": true,\n \"controlnets\": [\n {\n \"model\": \"value\",\n \"modelName\": \"value\",\n \"imagePath\": \"value\",\n \"strength\": 1,\n \"start\": 1,\n \"end\": 1\n }\n ],\n \"adetailer\": {\n \"enabled\": true,\n \"model\": \"value\",\n \"detector\": \"value\",\n \"maskMode\": \"segmentation\",\n \"attentionCouplePolicy\": \"strict-face-bbox\",\n \"adetailerAttentionCouplePolicy\": \"value\",\n \"adetailerMaskMode\": \"value\",\n \"confidence\": 1,\n \"iou\": 1,\n \"denoise\": 0.5,\n \"adetailerDenoise\": 1,\n \"dilate\": 4,\n \"maskBlur\": 4,\n \"maxDetections\": 2,\n \"dropSize\": 1,\n \"positivePrompt\": \"value\",\n \"negativePrompt\": \"value\",\n \"detectionOrder\": \"value\",\n \"timing\": \"pre-upscale\",\n \"adetailerTiming\": \"value\"\n },\n \"adetailerPositive\": \"value\",\n \"adetailerNegative\": \"value\",\n \"adetailerDetectionOrder\": \"value\",\n \"attentionCouple\": {\n \"enabled\": true,\n \"globalPromptWeight\": 0.01,\n \"regions\": [\n {\n \"prompt\": \"value\",\n \"maskPath\": \"value\",\n \"weight\": 1\n }\n ]\n },\n \"upscaleProfiles\": [\n {\n \"modelName\": \"value\",\n \"model\": \"value\",\n \"upscaleModelName\": \"value\",\n \"denoise\": 1\n }\n ],\n \"metadata\": {}\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/jobs/123/remix',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"prompt\\\":\\\"value\\\",\\\"mode\\\":\\\"txt2img\\\",\\\"presetId\\\":1,\\\"negativePrompt\\\":\\\"value\\\",\\\"modelName\\\":\\\"value\\\",\\\"loras\\\":[\\\"value\\\"],\\\"loraName\\\":\\\"value\\\",\\\"vaeName\\\":\\\"value\\\",\\\"imagePath\\\":\\\"value\\\",\\\"seed\\\":1,\\\"extraSeed\\\":1,\\\"extraSeedStrength\\\":1,\\\"rfShift\\\":1,\\\"steps\\\":1,\\\"cfg\\\":1,\\\"samplerName\\\":\\\"value\\\",\\\"scheduler\\\":\\\"value\\\",\\\"schedulerName\\\":\\\"value\\\",\\\"width\\\":1,\\\"height\\\":1,\\\"denoise\\\":1,\\\"scaleFactor\\\":1,\\\"batchSize\\\":1,\\\"promptControl\\\":true,\\\"retentionDays\\\":1,\\\"tags\\\":[\\\"value\\\"],\\\"sfwMode\\\":true,\\\"controlnets\\\":[{\\\"model\\\":\\\"value\\\",\\\"modelName\\\":\\\"value\\\",\\\"imagePath\\\":\\\"value\\\",\\\"strength\\\":1,\\\"start\\\":1,\\\"end\\\":1}],\\\"adetailer\\\":{\\\"enabled\\\":true,\\\"model\\\":\\\"value\\\",\\\"detector\\\":\\\"value\\\",\\\"maskMode\\\":\\\"segmentation\\\",\\\"attentionCouplePolicy\\\":\\\"strict-face-bbox\\\",\\\"adetailerAttentionCouplePolicy\\\":\\\"value\\\",\\\"adetailerMaskMode\\\":\\\"value\\\",\\\"confidence\\\":1,\\\"iou\\\":1,\\\"denoise\\\":0.5,\\\"adetailerDenoise\\\":1,\\\"dilate\\\":4,\\\"maskBlur\\\":4,\\\"maxDetections\\\":2,\\\"dropSize\\\":1,\\\"positivePrompt\\\":\\\"value\\\",\\\"negativePrompt\\\":\\\"value\\\",\\\"detectionOrder\\\":\\\"value\\\",\\\"timing\\\":\\\"pre-upscale\\\",\\\"adetailerTiming\\\":\\\"value\\\"},\\\"adetailerPositive\\\":\\\"value\\\",\\\"adetailerNegative\\\":\\\"value\\\",\\\"adetailerDetectionOrder\\\":\\\"value\\\",\\\"attentionCouple\\\":{\\\"enabled\\\":true,\\\"globalPromptWeight\\\":0.01,\\\"regions\\\":[{\\\"prompt\\\":\\\"value\\\",\\\"maskPath\\\":\\\"value\\\",\\\"weight\\\":1}]},\\\"upscaleProfiles\\\":[{\\\"modelName\\\":\\\"value\\\",\\\"model\\\":\\\"value\\\",\\\"upscaleModelName\\\":\\\"value\\\",\\\"denoise\\\":1}],\\\"metadata\\\":{}}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/generator/models": { "get": { "description": "List the generator model catalogue using the compatibility route retained for existing integrations.", "operationId": "listGeneratorModels", "parameters": [ { "description": "Include full LoRA catalog entries. Accepts `true/false`, `1/0`, `yes/no`, `on/off`.", "example": false, "in": "query", "name": "includeLoras", "schema": { "default": false, "description": "Include Loras value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "adetailer": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ], "checkpoints": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ], "loras": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ] }, "schema": { "$ref": "#/components/schemas/GeneratorModelCatalog" } } }, "description": "Model catalog payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "content": { "application/json": { "example": { "error": "value", "errorCode": "value", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List generator model catalog entries", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/models' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/models', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/models',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/models/checkpoints": { "get": { "description": "Search generator checkpoints by the supported query, ownership, availability, and pagination filters.", "operationId": "searchGeneratorCheckpoints", "parameters": [ { "description": "Search term (minimum 2 characters).", "example": "landscape", "in": "query", "name": "q", "schema": { "description": "Q value documented for this operation.", "type": "string" } }, { "description": "Maximum number of results.", "example": 100, "in": "query", "name": "limit", "schema": { "default": 100, "description": "Limit value documented for this operation. Minimum: 1. Maximum: 200.", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Optional base model filter (for example `sdxl` or `sd15`).", "example": "example-base-model", "in": "query", "name": "baseModel", "schema": { "description": "Base Model value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "baseModel": "value", "entries": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ], "limit": 1, "query": "value" }, "schema": { "description": "Fields describing 200 response for api generator models checkpoints in Developer API requests and responses.", "properties": { "baseModel": { "description": "Base Model associated with this 200 response for api generator models checkpoints; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "entries": { "description": "Ordered entries entries included with this 200 response for api generator models checkpoints; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorModelCatalogEntry" }, "type": "array" }, "limit": { "description": "Maximum number of records requested or returned in one page of this 200 response for api generator models checkpoints.", "type": "integer" }, "query": { "description": "Query associated with this 200 response for api generator models checkpoints; preserve server-returned values when passing them to another operation.", "type": "string" } }, "required": [ "query", "baseModel", "limit", "entries" ], "type": "object" } } }, "description": "Checkpoint search result list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search generator checkpoint catalog entries", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/models/checkpoints' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/models/checkpoints', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/models/checkpoints',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/models/loras": { "get": { "description": "Search generator LoRAs by the supported query, ownership, base-model, availability, and pagination filters.", "operationId": "searchGeneratorLoras", "parameters": [ { "description": "Search term (minimum 2 characters).", "example": "landscape", "in": "query", "name": "q", "schema": { "description": "Q value documented for this operation.", "type": "string" } }, { "description": "Maximum number of results.", "example": 100, "in": "query", "name": "limit", "schema": { "default": 100, "description": "Limit value documented for this operation. Minimum: 1. Maximum: 200.", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Optional base model filter (for example `sdxl` or `sd15`).", "example": "example-base-model", "in": "query", "name": "baseModel", "schema": { "description": "Base Model value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "baseModel": "value", "entries": [ { "baseModel": "value", "coverImage": "value", "coverRating": "value", "favoriteCount": 1, "modelCapabilities": [ "value" ], "modelId": 1, "modelTags": [ "value" ], "modelTitle": "value", "modelType": "value", "modelVersionCount": 1, "modelVersionRank": 1, "name": "value", "precision": "value", "previewImage": "value", "previewRating": "value", "rfRequiredNotes": [ "value" ], "triggerPrompts": [ "value" ], "uploaderId": 1, "uploaderProfilePicture": "value", "uploaderUsername": "value", "versionId": 1, "versionName": "value" } ], "limit": 1, "query": "value" }, "schema": { "description": "Fields describing 200 response for api generator models loras in Developer API requests and responses.", "properties": { "baseModel": { "description": "Base Model associated with this 200 response for api generator models loras; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "entries": { "description": "Ordered entries entries included with this 200 response for api generator models loras; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorModelCatalogEntry" }, "type": "array" }, "limit": { "description": "Maximum number of records requested or returned in one page of this 200 response for api generator models loras.", "type": "integer" }, "query": { "description": "Query associated with this 200 response for api generator models loras; preserve server-returned values when passing them to another operation.", "type": "string" } }, "required": [ "query", "baseModel", "limit", "entries" ], "type": "object" } } }, "description": "LoRA search result list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search generator LoRA catalog entries", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/models/loras' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/models/loras', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/models/loras',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/options": { "get": { "description": "Return the caller-specific image generation option catalogue, allowed limits, samplers, schedulers, and feature capabilities.", "operationId": "getGeneratorOptions", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "limits": { "adetailerAttentionCouplePolicies": [ "strict-face-bbox" ], "adetailerAttentionCouplePolicyDefault": "strict-face-bbox", "adetailerDetectionOrderDefault": "value", "adetailerDetectionOrders": [ "value" ], "adetailerDetectors": [ "value" ], "adetailerEnabled": true, "adetailerMaskModeDefault": "bbox-only", "adetailerMaskModes": [ "bbox-only" ], "adetailerModels": [ "value" ], "compareEnabled": true, "maxBatchSize": 1, "maxCfg": 1, "maxCompareTargets": 1, "maxPixels": 1, "maxResolution": 1, "maxScaleFactor": 1, "maxSteps": 1, "maxUpscaleProfiles": 1, "maxWeight": 1, "samplers": [ "value" ], "schedulers": [ "value" ] }, "modelCapabilities": {}, "modelDetails": { "adetailer": [ { "baseModel": "value", "displayName": "value", "name": "value", "precision": "value" } ], "checkpoints": [ { "baseModel": "value", "displayName": "value", "name": "value", "precision": "value" } ], "controlnets": [ { "baseModel": "value", "displayName": "value", "name": "value", "precision": "value" } ], "loras": [ { "baseModel": "value", "displayName": "value", "name": "value", "precision": "value" } ], "upscale": [ { "baseModel": "value", "displayName": "value", "name": "value", "precision": "value" } ], "vae": [ { "baseModel": "value", "displayName": "value", "name": "value", "precision": "value" } ] }, "models": { "adetailer": [ "value" ], "checkpoints": [ "value" ], "controlnets": [ "value" ], "loras": [ "value" ], "upscale": [ "value" ], "vae": [ "value" ] }, "quota": { "budgets": { "gpuMs": { "limit": 1, "remaining": 1, "used": 1 }, "profile": "value", "vramMb": { "limit": 1, "remaining": 1, "used": 1 } }, "daily": { "limit": 1, "remaining": 1, "used": 1 }, "nextDailyReliefAt": 1, "pending": { "limit": 1, "remaining": 1, "used": 1 }, "role": "value", "supporter": true, "supporterPreview": { "budgets": { "gpuMs": { "limit": 1, "remaining": 1, "used": 1 }, "profile": "value", "vramMb": { "limit": 1, "remaining": 1, "used": 1 } }, "daily": { "limit": 1, "remaining": 1, "used": 1 }, "pending": { "limit": 1, "remaining": 1, "used": 1 } }, "windowMs": 1, "windowResetsAt": 1, "windowStartedAt": 1 }, "rfRequiredNotes": {}, "settings": { "defaults": {}, "retentionOptions": [ 1 ] } }, "schema": { "$ref": "#/components/schemas/GeneratorOptionsResponse" } } }, "description": "Generator options payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "User not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get generator runtime options and per-user quota snapshot", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/options' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/options', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/options',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/presets": { "get": { "description": "List reusable generator presets owned by the authenticated caller with their current configuration summaries.", "operationId": "listGeneratorPresets", "parameters": [ { "description": "Preset scope filter.", "example": "mine", "in": "query", "name": "scope", "schema": { "description": "Scope value documented for this operation. Supported values: `mine`, `public`, `all`.", "enum": [ "mine", "public", "all" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "presets": [ { "createdAt": "2026-07-28T10:00:00.000Z", "description": "value", "id": 1, "isPublic": true, "name": "value", "ownerId": 1, "payload": {}, "updatedAt": "2026-07-28T10:00:00.000Z" } ] }, "schema": { "description": "Fields describing 200 response for api generator presets in Developer API requests and responses.", "properties": { "presets": { "description": "Ordered presets entries included with this 200 response for api generator presets; an empty list means none are available.", "items": { "$ref": "#/components/schemas/GeneratorPreset" }, "type": "array" } }, "required": [ "presets" ], "type": "object" } } }, "description": "Preset list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List generator presets", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/presets' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/presets', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/presets',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a reusable generator preset for the authenticated caller from a validated name and generation configuration.", "operationId": "createGeneratorPreset", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "value", "isPublic": true, "name": "value", "payload": {} }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "isPublic": { "description": "Only applied for staff roles.", "type": "boolean" }, "name": { "description": "Human-readable name for this request payload; it is not a stable identifier.", "type": "string" }, "payload": { "additionalProperties": true, "description": "Structured payload details for this request payload.", "type": "object" } }, "required": [ "name", "payload" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "preset": { "createdAt": "2026-07-28T10:00:00.000Z", "description": "value", "id": 1, "isPublic": true, "name": "value", "ownerId": 1, "payload": {}, "updatedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "description": "Fields describing 201 response for api generator presets in Developer API requests and responses.", "properties": { "preset": { "$ref": "#/components/schemas/GeneratorPreset" } }, "required": [ "preset" ], "type": "object" } } }, "description": "Preset created.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a generator preset", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/presets' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"name\":\"value\",\"description\":\"value\",\"isPublic\":true,\"payload\":{}}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/presets', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"name\": \"value\",\n \"description\": \"value\",\n \"isPublic\": true,\n \"payload\": {}\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/presets',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"name\\\":\\\"value\\\",\\\"description\\\":\\\"value\\\",\\\"isPublic\\\":true,\\\"payload\\\":{}}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/generator/presets/{id}": { "delete": { "description": "Delete one caller-owned generator preset. Repeating the operation leaves the preset absent.", "operationId": "deleteGeneratorPreset", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "deleted": true, "id": 1 }, "schema": { "description": "Fields describing 200 response for api generator presets id in Developer API requests and responses.", "properties": { "deleted": { "description": "Whether deleted applies to this 200 response for api generator presets id.", "type": "boolean" }, "id": { "description": "Stable identifier for the 200 response for api generator presets id; use it in subsequent API calls instead of a display name.", "type": "integer" } }, "required": [ "deleted", "id" ], "type": "object" } } }, "description": "Preset deleted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid preset id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not authorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Preset not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a generator preset", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/generator/presets/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/presets/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/generator/presets/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one reusable generator preset owned by the authenticated caller, including its validated configuration.", "operationId": "getGeneratorPreset", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "preset": { "createdAt": "2026-07-28T10:00:00.000Z", "description": "value", "id": 1, "isPublic": true, "name": "value", "ownerId": 1, "payload": {}, "updatedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "description": "Fields describing 200 response for api generator presets id in Developer API requests and responses.", "properties": { "preset": { "$ref": "#/components/schemas/GeneratorPreset" } }, "required": [ "preset" ], "type": "object" } } }, "description": "Preset payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid preset id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not authorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Preset not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get a generator preset by id", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/presets/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/presets/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/presets/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update the supplied fields of a caller-owned generator preset while preserving unspecified configuration.", "operationId": "updateGeneratorPreset", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "value", "isPublic": true, "name": "value", "payload": {} }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "nullable": true, "type": "string" }, "isPublic": { "description": "Staff only.", "type": "boolean" }, "name": { "description": "Human-readable name for this request payload; it is not a stable identifier.", "type": "string" }, "payload": { "additionalProperties": true, "description": "Structured payload details for this request payload.", "type": "object" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "preset": { "createdAt": "2026-07-28T10:00:00.000Z", "description": "value", "id": 1, "isPublic": true, "name": "value", "ownerId": 1, "payload": {}, "updatedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "description": "Fields describing 200 response for api generator presets id in Developer API requests and responses.", "properties": { "preset": { "$ref": "#/components/schemas/GeneratorPreset" } }, "required": [ "preset" ], "type": "object" } } }, "description": "Preset updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload or no updates provided.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not authorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Preset not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update a generator preset", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/generator/presets/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"name\":\"value\",\"description\":\"value\",\"isPublic\":true,\"payload\":{}}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/presets/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"name\": \"value\",\n \"description\": \"value\",\n \"isPublic\": true,\n \"payload\": {}\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/generator/presets/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"name\\\":\\\"value\\\",\\\"description\\\":\\\"value\\\",\\\"isPublic\\\":true,\\\"payload\\\":{}}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/generator/presets/{id}/export": { "get": { "description": "Export one caller-owned generator preset as portable JSON with a download-safe filename.", "operationId": "exportGeneratorPreset", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "exportedAt": "2026-07-28T10:00:00.000Z", "preset": { "description": "value", "name": "value", "payload": {} }, "version": 1 }, "schema": { "$ref": "#/components/schemas/GeneratorPresetExport" } } }, "description": "Downloadable preset export payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid preset id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not authorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Preset not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Preset payload could not be exported.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Export a generator preset as JSON", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/presets/123/export' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/presets/123/export', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/presets/123/export',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/state": { "get": { "description": "Return public image-generator availability and maintenance state. The response does not expose worker credentials, queues, or administrative controls.", "operationId": "getGeneratorState", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "allowModeratorsWhenDisabled": true, "enabled": true, "message": "value", "regionalPromptsAdminsOnly": true }, "schema": { "$ref": "#/components/schemas/GeneratorState" } } }, "description": "Current generator state.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get generator availability state", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/state' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/state', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/state',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/tags/autocomplete": { "get": { "description": "Return bounded generator prompt-tag suggestions for the supplied prefix so clients can implement accessible autocomplete.", "operationId": "listGeneratorTagSuggestions", "parameters": [ { "description": "Search term.", "example": "landscape", "in": "query", "name": "q", "schema": { "description": "Q value documented for this operation.", "type": "string" } }, { "description": "Limit provided in the query.", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "description": "Limit value documented for this operation. Minimum: 1. Maximum: 50.", "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "Include alias matches.", "example": true, "in": "query", "name": "includeAliases", "schema": { "default": true, "description": "Include Aliases value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "tags": [ { "aliases": [ "value" ], "count": 1, "display": "value", "name": "value", "type": 1 } ] }, "schema": { "$ref": "#/components/schemas/GeneratorTagSuggestionsResponse" } } }, "description": "Tag suggestion list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Autocomplete generator tags", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/tags/autocomplete' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/tags/autocomplete', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/tags/autocomplete',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/uploads": { "post": { "description": "Upload one validated image source for subsequent image-generation jobs and return its caller-bound temporary identifier.", "operationId": "uploadGeneratorSource", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "image": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "image": { "description": "Image associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "kind": { "default": "SOURCE", "description": "Upload classification used for TTL/quota tracking. Unknown values fall back to `SOURCE`.", "enum": [ "SOURCE", "MASK", "ATTENTION", "CONTROLNET", "OTHER" ], "type": "string" } }, "required": [ "image" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "expiresAt": "2026-07-28T10:00:00.000Z", "mimeType": "value", "originalName": "value", "path": "value", "size": 1, "ttlSeconds": 1 }, "schema": { "$ref": "#/components/schemas/GeneratorUploadResponse" } } }, "description": "Upload stored successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "content": { "application/json": { "example": { "error": "value", "errorCode": "value", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "$ref": "#/components/schemas/GeneratorError" } } }, "description": "Missing file or invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "User banned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "User not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "413": { "description": "Upload quota exceeded or file too large.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Upload storage error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload a source or mask image for generator flows", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/uploads' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/uploads', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/uploads',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/generator/uploads/touch": { "post": { "description": "Extend the lifetime of a bounded set of caller-owned temporary generator uploads without creating new upload records.", "operationId": "touchGeneratorUploads", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "paths": [ "generator/source-123.png" ] }, "schema": { "$ref": "#/components/schemas/GeneratorUploadTouchRequest" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "expiresAt": "2026-07-28T10:00:00.000Z", "missing": [ "value" ], "touched": 1, "ttlSeconds": 1 }, "schema": { "$ref": "#/components/schemas/GeneratorUploadTouchResponse" } } }, "description": "Upload expiry refreshed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid or empty paths payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Not authenticated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "User banned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "content": { "application/json": { "example": { "error": "value", "errorCode": "value", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "description": "404 response for api generator uploads touch value documented for this operation.", "oneOf": [ { "$ref": "#/components/schemas/GeneratorError" }, { "$ref": "#/components/schemas/GeneratorUploadTouchResponse" } ] } } }, "description": "User not found or provided paths no longer exist.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Keepalive operation failed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Refresh expiry for existing generator upload paths", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/uploads/touch' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"paths\":[\"generator/source-123.png\"]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/uploads/touch', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"paths\": [\n \"generator/source-123.png\"\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/uploads/touch',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"paths\\\":[\\\"generator/source-123.png\\\"]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/generator/video/events": { "get": { "description": "Open a server-sent event stream for caller-owned video-generation job state changes. Clients should reconnect with bounded backoff.", "operationId": "streamGeneratorVideoEvents", "parameters": [], "responses": { "200": { "content": { "text/event-stream": { "example": "event: connected\ndata: {\"ok\":true}\n\nevent: heartbeat\ndata: {\"ts\":1786057200000}\n\nevent: job\ndata: {\"job\":{\"id\":\"27b28ca4-f488-4260-9e8c-f1897d06c51d\",\"status\":\"running\",\"progress\":0.42}}\n", "schema": { "description": "UTF-8 server-sent event frames.", "type": "string" } } }, "description": "Server-sent video job updates.", "headers": { "Cache-Control": { "description": "Prevents buffering and caching.", "schema": { "example": "no-cache, no-transform", "type": "string" } }, "X-Accel-Buffering": { "description": "Disables reverse-proxy response buffering.", "schema": { "enum": [ "no" ], "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Stream video job, queue-position, and ETA updates", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/events' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/events', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/events',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe", "x-sse-events": { "connected": { "$ref": "#/components/schemas/GeneratorVideoSseConnectedEvent" }, "heartbeat": { "$ref": "#/components/schemas/GeneratorVideoSseHeartbeatEvent" }, "job": { "$ref": "#/components/schemas/GeneratorVideoSseJobEvent" } } } }, "/api/generator/video/jobs": { "get": { "description": "List the authenticated caller’s video-generation jobs with bounded pagination, state, progress, and output summaries.", "operationId": "listGeneratorVideoJobs", "parameters": [ { "description": "Maximum jobs to return.", "example": 30, "in": "query", "name": "limit", "schema": { "default": 30, "description": "Limit value documented for this operation. Minimum: 1. Maximum: 100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Job ID from which to continue.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "query", "name": "cursor", "schema": { "description": "Cursor value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } }, { "description": "Optional lifecycle-status filter.", "example": "queued", "in": "query", "name": "status", "schema": { "description": "Status value documented for this operation. Supported values: `queued`, `running`, `finalizing`, `completed`, `failed`, `cancelled`.", "enum": [ "queued", "running", "finalizing", "completed", "failed", "cancelled" ], "type": "string" } }, { "description": "Optional generation-mode filter.", "example": "txt2video", "in": "query", "name": "mode", "schema": { "description": "Mode value documented for this operation. Supported values: `txt2video`, `image2video`.", "enum": [ "txt2video", "image2video" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "jobs": [ { "cfg": 1, "completedAt": "2026-07-28T10:00:00.000Z", "createdAt": "2026-07-28T10:00:00.000Z", "creditCost": 1, "downloadUrl": "value", "durationSeconds": 1, "error": "value", "estimatedCompletionMs": 1, "estimatedRemainingMs": 1, "estimatedRenderMs": 1, "expiresAt": "2026-07-28T10:00:00.000Z", "finalizationMs": 1, "firstFrameUrl": "value", "fps": 24, "frames": 124, "hasFirstFrame": true, "hasLastFrame": true, "height": 32, "id": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "lastFrameUrl": "value", "metadata": { "aspectRatio": "source", "audioEnabled": true, "creditCost": 1, "resolutionBucket": 384, "sfwMode": true, "sourceFit": "source" }, "mode": "txt2video", "negativePrompt": "value", "outputBytes": 1, "outputDurationSeconds": 1, "outputUrl": "value", "position": 1, "processingMs": 1, "progress": 1, "progressMessage": "value", "prompt": "value", "promptPreset": "value", "queueEtaMs": 1, "queueWaitMs": 1, "remoteRenderMs": 1, "safety": { "error": "value", "outputs": {}, "reason": "value", "review": { "actorId": 1, "actorRole": "value", "locked": true, "note": "value", "reason": "value", "reviewedAt": 1, "status": "ok" }, "sfwMode": true, "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scheduler": "value", "seed": "42", "startedAt": "2026-07-28T10:00:00.000Z", "status": "queued", "steps": 15, "taggerTags": [ "value" ], "totalElapsedMs": 1, "width": 32 } ], "nextCursor": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "quota": { "limit": 1, "pending": 1, "pendingLimit": 1, "remaining": 1, "resetAt": "2026-07-28T10:00:00.000Z", "tier": "user", "unlimitedOverride": true, "used": 1 } }, "schema": { "$ref": "#/components/schemas/GeneratorVideoJobListResponse" } } }, "description": "Video job history and current quota.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List the current user's video generation jobs", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/jobs' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/jobs',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a video-generation job from validated parameters, caller-visible models, and authorized source assets.", "operationId": "createGeneratorVideoJob", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "aspectRatio": "4:3", "audioEnabled": false, "frames": 124, "mode": "txt2video", "negativePrompt": "flicker, unstable motion, warped anatomy", "prompt": "Integrated multimodal description: A fox runs through a misty forest while the camera tracks alongside.", "promptPreset": "cinematic-scene", "resolutionBucket": 512, "seed": "42", "sfwMode": true, "steps": 25 }, "schema": { "$ref": "#/components/schemas/GeneratorVideoCreateRequest" } } }, "description": "Mode- and duration-specific video generation request.", "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "job": { "cfg": 1, "completedAt": "2026-07-28T10:00:00.000Z", "createdAt": "2026-07-28T10:00:00.000Z", "creditCost": 1, "downloadUrl": "value", "durationSeconds": 1, "error": "value", "estimatedCompletionMs": 1, "estimatedRemainingMs": 1, "estimatedRenderMs": 1, "expiresAt": "2026-07-28T10:00:00.000Z", "finalizationMs": 1, "firstFrameUrl": "value", "fps": 24, "frames": 124, "hasFirstFrame": true, "hasLastFrame": true, "height": 32, "id": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "lastFrameUrl": "value", "metadata": { "aspectRatio": "source", "audioEnabled": true, "creditCost": 1, "resolutionBucket": 384, "sfwMode": true, "sourceFit": "source" }, "mode": "txt2video", "negativePrompt": "value", "outputBytes": 1, "outputDurationSeconds": 1, "outputUrl": "value", "position": 1, "processingMs": 1, "progress": 1, "progressMessage": "value", "prompt": "value", "promptPreset": "value", "queueEtaMs": 1, "queueWaitMs": 1, "remoteRenderMs": 1, "safety": { "error": "value", "outputs": {}, "reason": "value", "review": { "actorId": 1, "actorRole": "value", "locked": true, "note": "value", "reason": "value", "reviewedAt": 1, "status": "ok" }, "sfwMode": true, "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scheduler": "value", "seed": "42", "startedAt": "2026-07-28T10:00:00.000Z", "status": "queued", "steps": 15, "taggerTags": [ "value" ], "totalElapsedMs": 1, "width": 32 }, "quota": { "limit": 1, "pending": 1, "pendingLimit": 1, "remaining": 1, "resetAt": "2026-07-28T10:00:00.000Z", "tier": "user", "unlimitedOverride": true, "used": 1 } }, "schema": { "$ref": "#/components/schemas/GeneratorVideoJobWithQuotaResponse" } } }, "description": "Video job queued with quota reserved.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } }, "operationConflict": { "summary": "Operation-specific error", "value": { "error": "The requested service is temporarily unavailable.", "errorCode": "SERVICE_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The operation is temporarily unavailable because a required service, dependency, or integration is unavailable. The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Reserve quota and queue one remote video generation job", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/video/jobs' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"mode\":\"txt2video\",\"prompt\":\"Integrated multimodal description: A fox runs through a misty forest while the camera tracks alongside.\",\"negativePrompt\":\"flicker, unstable motion, warped anatomy\",\"promptPreset\":\"cinematic-scene\",\"resolutionBucket\":512,\"aspectRatio\":\"4:3\",\"frames\":124,\"steps\":25,\"seed\":\"42\",\"audioEnabled\":false,\"sfwMode\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"mode\": \"txt2video\",\n \"prompt\": \"Integrated multimodal description: A fox runs through a misty forest while the camera tracks alongside.\",\n \"negativePrompt\": \"flicker, unstable motion, warped anatomy\",\n \"promptPreset\": \"cinematic-scene\",\n \"resolutionBucket\": 512,\n \"aspectRatio\": \"4:3\",\n \"frames\": 124,\n \"steps\": 25,\n \"seed\": \"42\",\n \"audioEnabled\": false,\n \"sfwMode\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/video/jobs',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"mode\\\":\\\"txt2video\\\",\\\"prompt\\\":\\\"Integrated multimodal description: A fox runs through a misty forest while the camera tracks alongside.\\\",\\\"negativePrompt\\\":\\\"flicker, unstable motion, warped anatomy\\\",\\\"promptPreset\\\":\\\"cinematic-scene\\\",\\\"resolutionBucket\\\":512,\\\"aspectRatio\\\":\\\"4:3\\\",\\\"frames\\\":124,\\\"steps\\\":25,\\\"seed\\\":\\\"42\\\",\\\"audioEnabled\\\":false,\\\"sfwMode\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/generator/video/jobs/{id}": { "delete": { "description": "Delete one caller-owned video-generation job and its managed outputs when runtime state permits. Repeating the request leaves it absent.", "operationId": "deleteGeneratorVideoJob", "parameters": [ { "description": "Video job ID.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Video job deleted with no response body.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Soft-delete a terminal video job and remove its output", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/generator/video/jobs/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/generator/video/jobs/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one video-generation job owned by the authenticated caller, including progress, parameters, moderation state, and output metadata.", "operationId": "getGeneratorVideoJob", "parameters": [ { "description": "Video job ID.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "job": { "cfg": 1, "completedAt": "2026-07-28T10:00:00.000Z", "createdAt": "2026-07-28T10:00:00.000Z", "creditCost": 1, "downloadUrl": "value", "durationSeconds": 1, "error": "value", "estimatedCompletionMs": 1, "estimatedRemainingMs": 1, "estimatedRenderMs": 1, "expiresAt": "2026-07-28T10:00:00.000Z", "finalizationMs": 1, "firstFrameUrl": "value", "fps": 24, "frames": 124, "hasFirstFrame": true, "hasLastFrame": true, "height": 32, "id": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "lastFrameUrl": "value", "metadata": { "aspectRatio": "source", "audioEnabled": true, "creditCost": 1, "resolutionBucket": 384, "sfwMode": true, "sourceFit": "source" }, "mode": "txt2video", "negativePrompt": "value", "outputBytes": 1, "outputDurationSeconds": 1, "outputUrl": "value", "position": 1, "processingMs": 1, "progress": 1, "progressMessage": "value", "prompt": "value", "promptPreset": "value", "queueEtaMs": 1, "queueWaitMs": 1, "remoteRenderMs": 1, "safety": { "error": "value", "outputs": {}, "reason": "value", "review": { "actorId": 1, "actorRole": "value", "locked": true, "note": "value", "reason": "value", "reviewedAt": 1, "status": "ok" }, "sfwMode": true, "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scheduler": "value", "seed": "42", "startedAt": "2026-07-28T10:00:00.000Z", "status": "queued", "steps": 15, "taggerTags": [ "value" ], "totalElapsedMs": 1, "width": 32 } }, "schema": { "$ref": "#/components/schemas/GeneratorVideoJobEnvelope" } } }, "description": "Video job.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get one video generation job", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/jobs/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/jobs/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/video/jobs/{id}/cancel": { "post": { "description": "Cancel one caller-owned video-generation job when its current state allows cancellation. Repeated calls do not create additional work.", "operationId": "cancelGeneratorVideoJob", "parameters": [ { "description": "Video job ID.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "job": { "cfg": 1, "completedAt": "2026-07-28T10:00:00.000Z", "createdAt": "2026-07-28T10:00:00.000Z", "creditCost": 1, "downloadUrl": "value", "durationSeconds": 1, "error": "value", "estimatedCompletionMs": 1, "estimatedRemainingMs": 1, "estimatedRenderMs": 1, "expiresAt": "2026-07-28T10:00:00.000Z", "finalizationMs": 1, "firstFrameUrl": "value", "fps": 24, "frames": 124, "hasFirstFrame": true, "hasLastFrame": true, "height": 32, "id": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "lastFrameUrl": "value", "metadata": { "aspectRatio": "source", "audioEnabled": true, "creditCost": 1, "resolutionBucket": 384, "sfwMode": true, "sourceFit": "source" }, "mode": "txt2video", "negativePrompt": "value", "outputBytes": 1, "outputDurationSeconds": 1, "outputUrl": "value", "position": 1, "processingMs": 1, "progress": 1, "progressMessage": "value", "prompt": "value", "promptPreset": "value", "queueEtaMs": 1, "queueWaitMs": 1, "remoteRenderMs": 1, "safety": { "error": "value", "outputs": {}, "reason": "value", "review": { "actorId": 1, "actorRole": "value", "locked": true, "note": "value", "reason": "value", "reviewedAt": 1, "status": "ok" }, "sfwMode": true, "status": "ok", "updatedAt": 1 }, "samplerName": "value", "scheduler": "value", "seed": "42", "startedAt": "2026-07-28T10:00:00.000Z", "status": "queued", "steps": 15, "taggerTags": [ "value" ], "totalElapsedMs": 1, "width": 32 }, "quota": { "limit": 1, "pending": 1, "pendingLimit": 1, "remaining": 1, "resetAt": "2026-07-28T10:00:00.000Z", "tier": "user", "unlimitedOverride": true, "used": 1 } }, "schema": { "$ref": "#/components/schemas/GeneratorVideoJobWithQuotaResponse" } } }, "description": "Cancelled video job and updated quota.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Cancel a queued or active video job", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorWrite", "x-api-key-required-scope-mask": 131072, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/generator/video/jobs/123/cancel' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs/123/cancel', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/generator/video/jobs/123/cancel',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/generator/video/jobs/{id}/download": { "get": { "description": "Download a completed caller-owned video output with HTTP Range support and an attachment filename.", "operationId": "downloadGeneratorVideoJob", "parameters": [ { "description": "Video job ID.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } }, { "description": "Optional RFC 7233 byte range.", "in": "header", "name": "Range", "required": false, "schema": { "description": "Range value documented for this operation.", "example": "bytes=0-1048575", "pattern": "^bytes=[0-9]*-[0-9]*$", "type": "string" } } ], "responses": { "200": { "content": { "video/mp4": { "schema": { "description": "200 response for api generator video jobs id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Complete H.264 MP4 attachment.", "headers": { "Accept-Ranges": { "description": "Supported range unit.", "schema": { "enum": [ "bytes" ], "type": "string" } }, "Cache-Control": { "description": "Private no-store policy.", "schema": { "example": "private, no-store", "type": "string" } }, "Content-Disposition": { "description": "Attachment filename disposition.", "schema": { "type": "string" } }, "Content-Length": { "description": "Response bytes.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "video/mp4": { "schema": { "description": "206 response for api generator video jobs id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Requested H.264 MP4 byte range.", "headers": { "Accept-Ranges": { "description": "Supported range unit.", "schema": { "enum": [ "bytes" ], "type": "string" } }, "Cache-Control": { "description": "Private no-store policy.", "schema": { "example": "private, no-store", "type": "string" } }, "Content-Disposition": { "description": "Attachment filename disposition.", "schema": { "type": "string" } }, "Content-Length": { "description": "Response bytes.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Content-Range": { "description": "Served byte range and total size.", "schema": { "example": "bytes 0-1048575/8388608", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": "value", "errorCode": "GENERATOR_OUTPUT_PENDING_REVIEW", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "anyOf": [ { "$ref": "#/components/schemas/GeneratorVideoSafetyRestriction" }, { "$ref": "#/components/schemas/ApiError" } ], "description": "403 response for api generator video jobs id download value documented for this operation." } } }, "description": "Output is pending review, quarantined, or the caller lacks permission.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "416": { "content": { "text/plain": { "schema": { "description": "416 response for api generator video jobs id download value documented for this operation.", "example": "Range Not Satisfiable", "type": "string" } } }, "description": "Requested byte range is outside the stored video output.", "headers": { "Content-Range": { "description": "Unsatisfied range and complete representation length.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download a completed generated video", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/jobs/123/download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs/123/download', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/jobs/123/download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/video/jobs/{id}/output": { "get": { "description": "Stream a completed caller-owned video output with HTTP Range support for media players and resumable consumers.", "operationId": "streamGeneratorVideoOutput", "parameters": [ { "description": "Video job ID.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } }, { "description": "Optional RFC 7233 byte range for seeking.", "in": "header", "name": "Range", "required": false, "schema": { "description": "Range value documented for this operation.", "example": "bytes=0-1048575", "pattern": "^bytes=[0-9]*-[0-9]*$", "type": "string" } } ], "responses": { "200": { "content": { "video/mp4": { "schema": { "description": "200 response for api generator video jobs id output value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Complete H.264 MP4 output.", "headers": { "Accept-Ranges": { "description": "Supported range unit.", "schema": { "enum": [ "bytes" ], "type": "string" } }, "Cache-Control": { "description": "Private no-store policy.", "schema": { "example": "private, no-store", "type": "string" } }, "Content-Disposition": { "description": "Inline filename disposition.", "schema": { "type": "string" } }, "Content-Length": { "description": "Response bytes.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "video/mp4": { "schema": { "description": "206 response for api generator video jobs id output value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Requested H.264 MP4 byte range.", "headers": { "Accept-Ranges": { "description": "Supported range unit.", "schema": { "enum": [ "bytes" ], "type": "string" } }, "Cache-Control": { "description": "Private no-store policy.", "schema": { "example": "private, no-store", "type": "string" } }, "Content-Disposition": { "description": "Inline filename disposition.", "schema": { "type": "string" } }, "Content-Length": { "description": "Response bytes.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Content-Range": { "description": "Served byte range and total size.", "schema": { "example": "bytes 0-1048575/8388608", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "example": { "error": "value", "errorCode": "GENERATOR_OUTPUT_PENDING_REVIEW", "safetyReason": "value", "safetyStatus": "pending_review" }, "schema": { "anyOf": [ { "$ref": "#/components/schemas/GeneratorVideoSafetyRestriction" }, { "$ref": "#/components/schemas/ApiError" } ], "description": "403 response for api generator video jobs id output value documented for this operation." } } }, "description": "Output is pending review, quarantined, or the caller lacks permission.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "416": { "content": { "text/plain": { "schema": { "description": "416 response for api generator video jobs id output value documented for this operation.", "example": "Range Not Satisfiable", "type": "string" } } }, "description": "Requested byte range is outside the stored video output.", "headers": { "Content-Range": { "description": "Unsatisfied range and complete representation length.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Stream a completed generated video", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/jobs/123/output' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs/123/output', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/jobs/123/output',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/video/jobs/{id}/source/{slot}": { "get": { "description": "Stream an authorized source asset for a caller-owned video-generation job. The slot identifies a documented input position.", "operationId": "getGeneratorVideoSource", "parameters": [ { "description": "Video job ID.", "example": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation. Format: uuid.", "format": "uuid", "type": "string" } }, { "description": "Requested source-frame slot.", "example": "first", "in": "path", "name": "slot", "required": true, "schema": { "description": "Slot value documented for this operation. Supported values: `first`, `last`.", "enum": [ "first", "last" ], "type": "string" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "description": "200 response for api generator video jobs id source slot value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/png": { "schema": { "description": "200 response for api generator video jobs id source slot value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/webp": { "schema": { "description": "200 response for api generator video jobs id source slot value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Source image bytes in the stored format.", "headers": { "Cache-Control": { "description": "Private no-store policy.", "schema": { "example": "private, no-store", "type": "string" } }, "Content-Length": { "description": "Response bytes.", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Stream an owned or staff-visible video source frame", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/jobs/123/source/value' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/jobs/123/source/value', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/jobs/123/source/value',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/video/options": { "get": { "description": "Return the caller-specific video generation option catalogue, supported models, limits, and input capabilities.", "operationId": "getGeneratorVideoOptions", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "aspectRatios": [ { "height": 1, "id": "source", "label": "value", "sourceOnly": true, "width": 1 } ], "capabilities": { "audioOutput": true, "imageInput": true, "lastFrameInput": true, "ready": true }, "defaults": { "aspectRatio": "4:3", "audioEnabled": true, "cfg": 1, "fps": 24, "frames": 124, "imageAspectRatio": "source", "mode": "txt2video", "negativePrompt": "value", "resolutionBucket": 512, "samplerName": "value", "scheduler": "value", "sfwMode": true, "steps": 15 }, "durationOptions": [ { "creditCost": 1, "durationSeconds": 1, "estimateFactor": 1, "frames": 124, "label": "value", "maxResolutionBucket": 512 } ], "estimateModifiers": { "audio": 1, "defaultSteps": 1, "imageToVideo": 1, "lastFrame": 1 }, "limits": { "cfg": 1, "fps": 24, "frames": [ 124 ], "maxOutputBytes": 1, "maxPixels": 1, "maxSourceBytes": 1, "maxSourcePixels": 1, "maxSteps": 1, "minSteps": 1, "negativePromptChars": 1, "promptChars": 1, "retentionDays": 1 }, "modes": [ { "enabled": true, "id": "txt2video", "label": "value", "unavailableReason": "value" } ], "promptPresets": [ { "id": "cinematic-scene", "label": "value", "prompt": "value" } ], "quota": { "limit": 1, "pending": 1, "pendingLimit": 1, "remaining": 1, "resetAt": "2026-07-28T10:00:00.000Z", "tier": "user", "unlimitedOverride": true, "used": 1 }, "resolutionBuckets": [ { "estimate": { "confidence": "baseline", "maxSeconds": 1, "minSeconds": 1, "sampleCount": 1 }, "label": "value", "value": 384 } ], "resolutions": [ { "height": 1, "id": "value", "label": "value", "width": 1 } ] }, "schema": { "$ref": "#/components/schemas/GeneratorVideoOptionsResponse" } } }, "description": "Video generator options.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get video presets, limits, capabilities, and quota", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/options' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/options', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/options',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/generator/video/state": { "get": { "description": "Return caller-visible video-generator availability, maintenance state, and feature readiness.", "operationId": "getGeneratorVideoState", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "audience": "staff", "canEnqueue": true, "enabled": true, "message": "value", "staffOnly": true, "visible": true }, "schema": { "$ref": "#/components/schemas/GeneratorVideoState" } } }, "description": "Viewer-specific video generator state.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get video generator visibility and availability", "tags": [ "Generator" ], "x-api-key-required-scope": "GeneratorRead", "x-api-key-required-scope-mask": 65536, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/generator/video/state' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/generator/video/state', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/generator/video/state',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/illegal-content-notices": { "post": { "description": "Submit a good-faith illegal-content notice as a guest or authenticated caller with up to four evidence files. Authenticated retries may reuse an Idempotency-Key; guest clients must not automatically retry an ambiguous submission.", "operationId": "createIllegalContentNotice", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "category": "PRIVACY_OR_DOOXING", "description": "The published image contains personal information without consent.", "goodFaithConfirmed": true, "reporterEmail": "reporter@example.com", "targetTypeHint": "IMAGE", "targetUrl": "https://arcenciel.io/images/108" }, "schema": { "properties": { "attachments": { "description": "Optional validated screenshots, documents, or short media evidence.", "items": { "format": "binary", "type": "string" }, "maxItems": 4, "type": "array" }, "category": { "description": "Alleged illegal-content category. Known values: SCAM_OR_FRAUD, COUNTERFEIT_OR_ILLEGAL_GOODS, CHILD_SAFETY, SEXUAL_CONTENT_INVOLVING_MINORS, ILLEGAL_HATE_OR_HARASSMENT, PRIVACY_OR_DOOXING, IMPERSONATION_OR_DECEPTION, VIOLENCE_OR_THREATS, INTELLECTUAL_PROPERTY, OTHER_ILLEGAL_CONTENT. Clients must tolerate future values.", "example": "PRIVACY_OR_DOOXING", "type": "string" }, "description": { "description": "Concrete explanation of the allegedly illegal content and where it appears.", "maxLength": 4000, "minLength": 20, "type": "string" }, "evidence": { "description": "Optional textual evidence or supporting context.", "maxLength": 4000, "type": "string" }, "goodFaithConfirmed": { "description": "Explicit confirmation that the notice is submitted in good faith.", "enum": [ true ], "type": "boolean" }, "jurisdiction": { "description": "Optional relevant country or jurisdiction.", "maxLength": 120, "type": "string" }, "legalBasis": { "description": "Optional legal basis supplied by the reporter.", "maxLength": 800, "type": "string" }, "reporterEmail": { "description": "Required for guests; authenticated reporters may use the email stored on their account.", "format": "email", "maxLength": 160, "type": "string" }, "reporterName": { "description": "Optional reporter name used for case correspondence.", "maxLength": 120, "type": "string" }, "targetTypeHint": { "description": "Resolved notice target type. Known values: GENERIC_URL, MODEL, IMAGE, VIDEO, USER_PROFILE, AVATAR, BANNER, ARTICLE, COMMENT, COLLECTION. Clients must tolerate future values.", "example": "IMAGE", "type": "string" }, "targetUrl": { "description": "Arc en Ciel HTTPS URL or relative content path.", "type": "string" } }, "required": [ "targetUrl", "category", "description", "goodFaithConfirmed" ], "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "attachments": { "description": "Optional validated screenshots, documents, or short media evidence.", "items": { "format": "binary", "type": "string" }, "maxItems": 4, "type": "array" }, "category": { "description": "Alleged illegal-content category. Known values: SCAM_OR_FRAUD, COUNTERFEIT_OR_ILLEGAL_GOODS, CHILD_SAFETY, SEXUAL_CONTENT_INVOLVING_MINORS, ILLEGAL_HATE_OR_HARASSMENT, PRIVACY_OR_DOOXING, IMPERSONATION_OR_DECEPTION, VIOLENCE_OR_THREATS, INTELLECTUAL_PROPERTY, OTHER_ILLEGAL_CONTENT. Clients must tolerate future values.", "example": "PRIVACY_OR_DOOXING", "type": "string" }, "description": { "description": "Concrete explanation of the allegedly illegal content and where it appears.", "maxLength": 4000, "minLength": 20, "type": "string" }, "evidence": { "description": "Optional textual evidence or supporting context.", "maxLength": 4000, "type": "string" }, "goodFaithConfirmed": { "description": "Explicit confirmation that the notice is submitted in good faith.", "enum": [ true ], "type": "boolean" }, "jurisdiction": { "description": "Optional relevant country or jurisdiction.", "maxLength": 120, "type": "string" }, "legalBasis": { "description": "Optional legal basis supplied by the reporter.", "maxLength": 800, "type": "string" }, "reporterEmail": { "description": "Required for guests; authenticated reporters may use the email stored on their account.", "format": "email", "maxLength": 160, "type": "string" }, "reporterName": { "description": "Optional reporter name used for case correspondence.", "maxLength": 120, "type": "string" }, "targetTypeHint": { "description": "Resolved notice target type. Known values: GENERIC_URL, MODEL, IMAGE, VIDEO, USER_PROFILE, AVATAR, BANNER, ARTICLE, COMMENT, COLLECTION. Clients must tolerate future values.", "example": "IMAGE", "type": "string" }, "targetUrl": { "description": "Arc en Ciel HTTPS URL or relative content path.", "type": "string" } }, "required": [ "targetUrl", "category", "description", "goodFaithConfirmed" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "accessCode": null, "lookupUrl": "https://arcenciel.io/report-illegal-content?case=ICN-9A2C13", "publicId": "ICN-9A2C13", "status": "SUBMITTED", "targetLabel": "Evening portrait", "targetType": "IMAGE" }, "schema": { "$ref": "#/components/schemas/DeveloperIllegalContentNoticeCreateResponse" } } }, "description": "Notice accepted and a trackable case identifier was created.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing or invalid notice fields.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication failed when an invalid bearer token was supplied.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "Too many notice submissions from the same client.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Submit a public illegal-content notice", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "FeedbackWrite", "x-api-key-required-scope-mask": 4194304, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/illegal-content-notices' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"targetUrl\":\"https://arcenciel.io/images/108\",\"targetTypeHint\":\"IMAGE\",\"category\":\"PRIVACY_OR_DOOXING\",\"description\":\"The published image contains personal information without consent.\",\"reporterEmail\":\"reporter@example.com\",\"goodFaithConfirmed\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/illegal-content-notices', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"targetUrl\": \"https://arcenciel.io/images/108\",\n \"targetTypeHint\": \"IMAGE\",\n \"category\": \"PRIVACY_OR_DOOXING\",\n \"description\": \"The published image contains personal information without consent.\",\n \"reporterEmail\": \"reporter@example.com\",\n \"goodFaithConfirmed\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/illegal-content-notices',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"targetUrl\\\":\\\"https://arcenciel.io/images/108\\\",\\\"targetTypeHint\\\":\\\"IMAGE\\\",\\\"category\\\":\\\"PRIVACY_OR_DOOXING\\\",\\\"description\\\":\\\"The published image contains personal information without consent.\\\",\\\"reporterEmail\\\":\\\"reporter@example.com\\\",\\\"goodFaithConfirmed\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 10, "policyId": "illegal-content-submit", "scope": "user, trusted API key, or client IP", "windowSeconds": 600 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/illegal-content-notices/me": { "get": { "description": "List the 25 most recent illegal-content notices linked to the authenticated reporter. Staff-only identity, evidence, and moderation fields are excluded.", "operationId": "listMyIllegalContentNotices", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": [ { "category": "PRIVACY_OR_DOOXING", "createdAt": "2026-08-07T10:00:00.000Z", "publicId": "ICN-9A2C13", "status": "SUBMITTED", "targetType": "IMAGE", "targetUrl": "https://arcenciel.io/images/108", "updatedAt": "2026-08-07T10:00:00.000Z" } ], "schema": { "items": { "$ref": "#/components/schemas/DeveloperIllegalContentNoticeSummary" }, "type": "array" } } }, "description": "Recent account-linked notices ordered by most recently updated first.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List the current user's recent illegal-content notices", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "FeedbackRead", "x-api-key-required-scope-mask": 2097152, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/illegal-content-notices/me' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/illegal-content-notices/me', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/illegal-content-notices/me',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/illegal-content-notices/{publicId}": { "get": { "description": "Retrieve a case using the reporter account, affected-owner account, staff access, or the unguessable guest access code. The response is filtered for that viewer and never exposes staff-only contact or internal-note fields.", "operationId": "getIllegalContentNotice", "parameters": [ { "description": "Public case id returned when the notice was created.", "example": "ICN-9A2C13", "in": "path", "name": "publicId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Guest lookup secret. Prefer authenticated access where possible because query strings may be logged by clients.", "in": "query", "name": "accessToken", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "canRequestReview": false, "category": "PRIVACY_OR_DOOXING", "createdAt": "2026-08-07T10:00:00.000Z", "decisionReason": null, "description": "The published image contains personal information without consent.", "evidence": "The attached screenshot marks the relevant area.", "evidenceAttachments": [ { "downloadPath": "/api/illegal-content-notices/ICN-9A2C13/attachments/ev-01HZX3", "fileName": "evidence.png", "id": "ev-01HZX3", "mimeType": "image/png", "sizeBytes": 248122, "uploadedAt": "2026-08-07T10:00:00.000Z" } ], "jurisdiction": "DE", "legalBasis": "Applicable national privacy law.", "publicId": "ICN-9A2C13", "reviewRequestMessage": null, "status": "SUBMITTED", "targetId": 108, "targetType": "IMAGE", "targetTypeHint": "IMAGE", "targetUrl": "https://arcenciel.io/images/108", "updatedAt": "2026-08-07T10:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/DeveloperIllegalContentNoticeDetail" } } }, "description": "Notice detail visible to the current viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "The requested notice is not available to the current viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Notice not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve a single illegal-content notice by case id", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "FeedbackRead", "x-api-key-required-scope-mask": 2097152, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/illegal-content-notices/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/illegal-content-notices/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/illegal-content-notices/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/illegal-content-notices/{publicId}/attachments/{attachmentId}": { "get": { "description": "Download a private evidence attachment after applying the same reporter, affected-owner, staff, or guest-code visibility decision as the parent case. Do not persist guest access codes in logs.", "operationId": "downloadIllegalContentNoticeAttachment", "parameters": [ { "description": "Public case id returned when the notice was created.", "example": "ICN-9A2C13", "in": "path", "name": "publicId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Attachment id from the notice detail payload.", "example": "ev-01HZX3", "in": "path", "name": "attachmentId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Guest lookup secret. Never persist or emit this value in application logs.", "in": "query", "name": "accessToken", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } }, "application/pdf": { "schema": { "format": "binary", "type": "string" } }, "image/gif": { "schema": { "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "format": "binary", "type": "string" } }, "image/png": { "schema": { "format": "binary", "type": "string" } }, "image/webp": { "schema": { "format": "binary", "type": "string" } }, "text/plain": { "schema": { "format": "binary", "type": "string" } }, "video/mp4": { "schema": { "format": "binary", "type": "string" } }, "video/webm": { "schema": { "format": "binary", "type": "string" } } }, "description": "Complete private attachment stream.", "headers": { "Accept-Ranges": { "description": "Indicates byte-range support when available.", "schema": { "example": "bytes", "type": "string" } }, "Content-Disposition": { "description": "Sanitized original filename and inline or attachment disposition.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } }, "application/pdf": { "schema": { "format": "binary", "type": "string" } }, "image/gif": { "schema": { "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "format": "binary", "type": "string" } }, "image/png": { "schema": { "format": "binary", "type": "string" } }, "image/webp": { "schema": { "format": "binary", "type": "string" } }, "text/plain": { "schema": { "format": "binary", "type": "string" } }, "video/mp4": { "schema": { "format": "binary", "type": "string" } }, "video/webm": { "schema": { "format": "binary", "type": "string" } } }, "description": "Requested byte range of the private attachment.", "headers": { "Content-Disposition": { "description": "Sanitized original filename.", "schema": { "type": "string" } }, "Content-Range": { "description": "Returned byte range and complete attachment size.", "schema": { "example": "bytes 0-1023/4096", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "The requested attachment is not available to the current viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Notice or attachment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "416": { "description": "Requested byte range is not satisfiable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download an evidence attachment for a notice", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "FeedbackRead", "x-api-key-required-scope-mask": 2097152, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/illegal-content-notices/123/attachments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/illegal-content-notices/123/attachments/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/illegal-content-notices/123/attachments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/illegal-content-notices/{publicId}/review-request": { "post": { "description": "Reopen a finalized notice for review as its reporter or affected owner. Authenticated callers should reuse the same Idempotency-Key; guest callers use their access code and must not automatically retry.", "operationId": "requestIllegalContentNoticeReview", "parameters": [ { "description": "Public case id returned when the notice was created.", "example": "ICN-9A2C13", "in": "path", "name": "publicId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Optional guest access code if the request is not made while signed in.", "example": "example-access-token", "in": "query", "name": "accessToken", "schema": { "description": "Access Token value documented for this operation.", "type": "string" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "message": "The decision did not address the personal information visible in the attachment." }, "schema": { "properties": { "accessToken": { "description": "Guest access code. Prefer the request body over a query string to avoid URL logs.", "maxLength": 128, "type": "string" }, "message": { "description": "Why the finalized decision should be reviewed again.", "maxLength": 4000, "minLength": 20, "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Review requested.", "publicId": "ICN-9A2C13", "status": "SUBMITTED" }, "schema": { "$ref": "#/components/schemas/DeveloperNoticeReviewResponse" } } }, "description": "Review request recorded and the case was reopened for moderator review.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Review request message too short or invalid payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "The current viewer is not allowed to request review for this case.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Notice not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Review is only available after a final decision has been recorded. The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "Too many review requests from the same client.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Request another review for a finalized illegal-content notice", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "FeedbackWrite", "x-api-key-required-scope-mask": 4194304, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/illegal-content-notices/123/review-request' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"message\":\"The decision did not address the personal information visible in the attachment.\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/illegal-content-notices/123/review-request', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"message\": \"The decision did not address the personal information visible in the attachment.\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/illegal-content-notices/123/review-request',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"message\\\":\\\"The decision did not address the personal information visible in the attachment.\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 10, "policyId": "illegal-content-review", "scope": "user, trusted API key, or client IP", "windowSeconds": 600 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/images/bulk-download": { "post": { "description": "Stream a ZIP archive containing the visible original bytes for a bounded set of image identifiers. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "downloadImagesBulk", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "ids": [ 12, 44, 99 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "ids": { "description": "Ordered ids entries included with this request payload; an empty list means none are available.", "example": [ 12, 44, 99 ], "items": { "description": "Numeric ids item reported for this ids.", "type": "integer" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "ids" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/zip": { "schema": { "description": "200 response for api images bulk download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "ZIP archive containing downloadable selected images.", "headers": { "Content-Disposition": { "description": "Attachment filename generated for the streamed ZIP archive.", "schema": { "example": "attachment; filename=\"arcenciel-images-2026-08-07.zip\"", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing IDs or too many selected images.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "None of the requested images could be downloaded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download selected original image files as a ZIP archive", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/bulk-download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"ids\":[12,44,99]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/bulk-download', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"ids\": [\n 12,\n 44,\n 99\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/bulk-download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"ids\\\":[12,44,99]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/bulk-info": { "get": { "description": "Resolve lightweight visible metadata for a bounded set of image identifiers in one request. Missing or inaccessible identifiers are reported according to the documented response envelope.", "operationId": "getImagesBulk", "parameters": [ { "description": "Comma-separated image ids, for example `12,44,99`.", "example": "example-ids", "in": "query", "name": "ids", "required": true, "schema": { "description": "Ids value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "images": [ { "cfg": 1, "filePath": "value", "id": 1, "negativePrompt": "value", "prompt": "value", "sampler": "value", "seed": "value", "steps": 1 } ] }, "schema": { "description": "Fields describing 200 response for api images bulk info in Developer API requests and responses.", "properties": { "images": { "description": "Ordered images entries included with this 200 response for api images bulk info; an empty list means none are available.", "items": { "description": "Structured images item details for this images.", "properties": { "cfg": { "description": "Numeric cfg reported for this images item.", "nullable": true, "type": "number" }, "filePath": { "description": "Server-provided path for the file path associated with this images item; treat it as opaque.", "type": "string" }, "id": { "description": "Stable identifier for the images item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this images item; availability depends on visibility and privacy rules.", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this images item; availability depends on visibility and privacy rules.", "type": "string" }, "sampler": { "description": "Sampler associated with this images item; preserve server-returned values when passing them to another operation.", "type": "string" }, "seed": { "description": "Seed associated with this images item; preserve server-returned values when passing them to another operation.", "type": "string" }, "steps": { "description": "Numeric steps reported for this images item.", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" } }, "required": [ "images" ], "type": "object" } } }, "description": "Ordered image metadata entries.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "No valid ids were provided.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "One or more requested images were not found or are inaccessible.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve lightweight metadata for multiple image IDs", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/bulk-info' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/bulk-info', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/bulk-info',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/search": { "get": { "description": "Search visible images with pagination, rating, tag, model, and ownership filters. Anonymous and third-party callers receive only media permitted by publication and adult-content policies.", "operationId": "searchImages", "parameters": [ { "description": "Search query applied to title, description, prompt, and tags (comma-separated terms supported).", "example": "landscape", "in": "query", "name": "search", "schema": { "description": "Search value documented for this operation.", "type": "string" } }, { "description": "Sort order for images (hot = recent images sorted by reactions).", "example": "newest", "in": "query", "name": "sort", "schema": { "description": "Sort value documented for this operation. Supported values: `newest`, `oldest`, `reactions`, `random`, `hot`.", "enum": [ "newest", "oldest", "reactions", "random", "hot" ], "type": "string" } }, { "description": "Page number.", "example": 1, "in": "query", "name": "page", "schema": { "default": 1, "description": "Page value documented for this operation.", "type": "integer" } }, { "description": "Number of images per page (max 1000).", "example": 12, "in": "query", "name": "limit", "schema": { "default": 12, "description": "Limit value documented for this operation.", "type": "integer" } }, { "description": "Comma-separated list of ratings to include (safe, questionable, sensitive, explicit).", "example": "example-ratings", "in": "query", "name": "ratings", "schema": { "description": "Ratings value documented for this operation.", "type": "string" } }, { "description": "Filter images by uploader id.", "example": 1, "in": "query", "name": "userId", "schema": { "description": "User Id value documented for this operation.", "type": "integer" } }, { "description": "Auth only. Filter images reacted to by the current user (optionally specify a reaction type).", "example": "example-self-reacted", "in": "query", "name": "selfReacted", "schema": { "description": "Self Reacted value documented for this operation.", "type": "string" } }, { "description": "Auth only. Return images uploaded by users the current user follows.", "example": true, "in": "query", "name": "selfFollowing", "schema": { "description": "Self Following value documented for this operation.", "type": "boolean" } }, { "description": "Cursor for keyset pagination (use nextCursor from a previous response; only supported for newest/oldest).", "example": "next-page", "in": "query", "name": "cursor", "schema": { "description": "Cursor value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" } ], "hasMore": true, "limit": 1, "nextCursor": "value", "page": 1, "showcased": [ { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" } ], "totalCount": 1, "totalPages": 1 }, "schema": { "description": "Fields describing 200 response for api images search in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api images search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Image" }, "type": "array" }, "hasMore": { "description": "Whether another page of this 200 response for api images search is available after the current result.", "type": "boolean" }, "limit": { "description": "Maximum number of records requested or returned in one page of this 200 response for api images search.", "type": "integer" }, "nextCursor": { "description": "Opaque continuation token for the next page of this 200 response for api images search; absent or null means iteration is complete.", "nullable": true, "type": "string" }, "page": { "description": "One-based result page requested or returned for this 200 response for api images search.", "type": "integer" }, "showcased": { "description": "Ordered showcased entries included with this 200 response for api images search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Image" }, "type": "array" }, "totalCount": { "description": "Total number of matching records across all pages for this 200 response for api images search.", "type": "integer" }, "totalPages": { "description": "Total number of pages available at the current page size for this 200 response for api images search.", "type": "integer" } }, "type": "object" } } }, "description": "A paginated list of images.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search images with pagination and filtering", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/search' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/search', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/search',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "content-search", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/style-search/upload": { "post": { "description": "Upload up to three in-memory query images and return paginated visible style matches plus matcher capability metadata. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "searchImagesByStyleUpload", "parameters": [], "requestBody": { "content": { "multipart/form-data": { "example": { "image": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "backend": { "description": "Optional style matcher backend override.", "type": "string" }, "image": { "description": "Image associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "limit": { "default": 8, "description": "Maximum number of records requested or returned in one page of this request payload. Maximum: 50.", "maximum": 50, "type": "integer" } }, "required": [ "image" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "matches": [ { "id": 108, "score": 0.93 } ], "meta": { "inverted": false, "page": 0, "pageSize": 24, "serviceHealthy": true, "totalMatches": 1 } }, "schema": { "$ref": "#/components/schemas/DeveloperStyleSearchResponse" } } }, "description": "Style matches for the uploaded reference.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing or invalid upload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Style search access is restricted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "Style matcher is temporarily saturated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "description": "Style matcher unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload an image and retrieve style-similar matches.", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/style-search/upload' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/style-search/upload', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/style-search/upload',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/images/upload": { "post": { "description": "Upload up to twenty validated images with creator metadata and report accepted identifiers even when some files fail validation. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadImages", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "description": "example", "imageFiles": [ "example" ], "tags": "example", "title": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "type": "string" }, "imageFiles": { "description": "Array of image files.", "items": { "description": "Image Files item associated with this image files; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "type": "array" }, "tags": { "description": "Comma-separated list of tags.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" } }, "type": "object" } } }, "description": "Multipart form data for image upload.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "imageIds": [ 108, 109 ] }, "schema": { "$ref": "#/components/schemas/DeveloperImageUploadResponse" } } }, "description": "Images uploaded successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "imageIds": [ 108, 109 ] }, "schema": { "$ref": "#/components/schemas/DeveloperImageUploadResponse" } } }, "description": "Some images were rejected while the remaining images were stored.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request (e.g. no files uploaded or invalid file format).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload one or multiple images", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/upload' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/upload', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/upload',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/images/{id}": { "delete": { "description": "Delete a caller-managed image, its managed derivatives, and dependent associations after authorization checks. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "deleteImage", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Image deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden (not the owner or admin/mod).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete an image (only author or admin/mod)", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesDelete", "x-api-key-required-scope-mask": 128, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/images/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/images/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Transfer a visible image, preferring a generated WebP representation when supported and otherwise returning the original. Clients must honor the actual response Content-Type.", "operationId": "getImageContent", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "description": "200 response for api images id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/png": { "schema": { "description": "200 response for api images id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/webp": { "schema": { "description": "200 response for api images id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "The image file is returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve an image file (webp if supported, original otherwise)", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update supported metadata, prompt, generation parameters, tags, rating, and publication fields on a caller-managed image. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateImage", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "cfg": 1, "description": "value", "negativePrompt": "value", "prompt": "value", "sampler": "value", "seed": "value", "steps": 1, "title": "value" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "cfg": { "description": "Numeric cfg reported for this request payload.", "type": "number" }, "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "type": "string" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "sampler": { "description": "Sampler associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "seed": { "description": "Seed associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "steps": { "description": "Numeric steps reported for this request payload.", "type": "number" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "image": { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" }, "message": "Image updated successfully" }, "schema": { "$ref": "#/components/schemas/DeveloperImageMutationResponse" } } }, "description": "Image updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid input.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not allowed to edit).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Edit an existing image", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/images/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"title\":\"value\",\"description\":\"value\",\"prompt\":\"value\",\"negativePrompt\":\"value\",\"sampler\":\"value\",\"seed\":\"value\",\"cfg\":1,\"steps\":1}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"title\": \"value\",\n \"description\": \"value\",\n \"prompt\": \"value\",\n \"negativePrompt\": \"value\",\n \"sampler\": \"value\",\n \"seed\": \"value\",\n \"cfg\": 1,\n \"steps\": 1\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/images/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"title\\\":\\\"value\\\",\\\"description\\\":\\\"value\\\",\\\"prompt\\\":\\\"value\\\",\\\"negativePrompt\\\":\\\"value\\\",\\\"sampler\\\":\\\"value\\\",\\\"seed\\\":\\\"value\\\",\\\"cfg\\\":1,\\\"steps\\\":1}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/crosspost": { "post": { "description": "Associate a caller-managed image with a bounded set of caller-managed models without creating duplicate relationships. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "createImageCrosspost", "parameters": [ { "description": "ID of the image to crosspost.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "manual": true, "modelIds": [ 1 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "manual": { "description": "Whether the crosspost was made manually.", "type": "boolean" }, "modelIds": { "description": "Array of model IDs.", "items": { "description": "Numeric model ids item reported for this model ids.", "type": "integer" }, "type": "array" } }, "required": [ "modelIds" ], "type": "object" } } }, "description": "List of model IDs to crosspost to.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Crosspost created.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "No modelIds provided or too many models.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to crosspost this image.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Crosspost an image to one or more models", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/123/crosspost' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"modelIds\":[1],\"manual\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/crosspost', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"modelIds\": [\n 1\n ],\n \"manual\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/123/crosspost',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"modelIds\\\":[1],\\\"manual\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/crosspost/{modelId}": { "delete": { "description": "Remove the association between a caller-managed image and model without deleting either resource. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "removeImageCrosspost", "parameters": [ { "description": "ID of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "ID of the model to remove the crosspost from.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Crosspost deleted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to remove crosspost.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove a crosspost from an image", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesDelete", "x-api-key-required-scope-mask": 128, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/images/123/crosspost/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/crosspost/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/images/123/crosspost/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/dl": { "get": { "description": "Download the original bytes of a visible image through the compatibility alias. New integrations should prefer downloadImage while existing clients may continue using this stable alias.", "operationId": "downloadImageLegacy", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "200 response for api images id dl value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Binary file download of the image.", "headers": { "Content-Disposition": { "description": "Attachment disposition containing the sanitized original filename.", "schema": { "example": "attachment; filename=\"image-42.png\"", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or file missing on disk.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download the original image file (alias)", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/dl' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/dl', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/dl',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{id}/download": { "get": { "description": "Download the original bytes of a visible image with a server-provided filename. The download limiter applies in addition to normal read limits and callers should stream large responses.", "operationId": "downloadImage", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "200 response for api images id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Binary file download of the image.", "headers": { "Content-Disposition": { "description": "Attachment disposition containing the sanitized original filename.", "schema": { "example": "attachment; filename=\"image-42.png\"", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or file missing on disk.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download the original image file", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/download', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{id}/external-resources": { "get": { "description": "Resolve public local and external model resources associated with one visible image. Private dependency and management metadata remains restricted to authorized owners and staff.", "operationId": "listImageExternalResources", "parameters": [ { "description": "ID of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "externalResources": [ {} ], "resources": [ {} ] }, "schema": { "description": "Fields describing 200 response for api images id external resources in Developer API requests and responses.", "properties": { "externalResources": { "description": "Ordered external resources entries included with this 200 response for api images id external resources; an empty list means none are available.", "items": { "description": "Structured external resources item details for this external resources.", "type": "object" }, "type": "array" }, "resources": { "description": "Ordered resources entries included with this 200 response for api images id external resources; an empty list means none are available.", "items": { "description": "Structured resources item details for this resources.", "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Resource matches returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Resolve resources associated with an image", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/external-resources' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/external-resources', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/external-resources',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{id}/info": { "get": { "description": "Return visible metadata for one image, including public uploader, tag, model-version, reaction, and generated-variant information appropriate for the current caller.", "operationId": "getImage", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" }, "schema": { "$ref": "#/components/schemas/Image" } } }, "description": "Image metadata retrieved successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve image metadata by ID", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/info' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/info', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/info',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{id}/pinned": { "patch": { "description": "Set the explicit pin state of an image within a caller-managed model after validating both resource identifiers. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "setImagePin", "parameters": [ { "description": "ID of the image to pin or unpin.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "modelId": 1, "pin": true }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "modelId": { "description": "Target model id whose pinned image list should be updated.", "type": "integer" }, "pin": { "description": "When true the image is pinned; when false it is unpinned.", "type": "boolean" } }, "required": [ "modelId", "pin" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Pin state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing/invalid modelId or pin payload, or no state change possible.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to pin/unpin for the target model.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image or model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Pin or unpin an image", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/images/123/pinned' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"modelId\":1,\"pin\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/pinned', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"modelId\": 1,\n \"pin\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/images/123/pinned',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"modelId\\\":1,\\\"pin\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/prompt-analysis": { "get": { "description": "Group the visible prompt tokens of an image into semantic categories for inspection and UI presentation. The response may grow with new categories and clients must ignore unknown fields.", "operationId": "analyzeImagePrompt", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "analyzerVersion": "1.0.1", "description": [ "value" ], "dialect": "ANIMA", "groups": [ { "key": "value", "label": "value", "tags": [ { "canonical": "value", "match": "EXACT", "raw": "value", "source": "ACTIVATION" } ] } ], "summary": { "descriptionCount": 1, "tagCount": 1, "unclassifiedCount": 1 } }, "schema": { "description": "Fields describing 200 response for api images id prompt analysis in Developer API requests and responses.", "properties": { "analyzerVersion": { "description": "Analyzer Version associated with this 200 response for api images id prompt analysis; preserve server-returned values when passing them to another operation.", "example": "1.0.1", "type": "string" }, "description": { "description": "User-facing description of this 200 response for api images id prompt analysis; it may contain an empty string when no description was supplied.", "items": { "description": "Description item associated with this description; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" }, "dialect": { "description": "Dialect associated with this 200 response for api images id prompt analysis; preserve server-returned values when passing them to another operation. Supported values: `ANIMA`, `BOORU`, `MIXED`, `NATURAL`, `UNKNOWN`.", "enum": [ "ANIMA", "BOORU", "MIXED", "NATURAL", "UNKNOWN" ], "type": "string" }, "groups": { "description": "Non-empty groups in a stable display order.", "items": { "description": "Structured groups item details for this groups.", "properties": { "key": { "description": "Key associated with this groups item; preserve server-returned values when passing them to another operation.", "type": "string" }, "label": { "description": "Label associated with this groups item; preserve server-returned values when passing them to another operation.", "type": "string" }, "tags": { "description": "Ordered tags entries included with this groups item; an empty list means none are available.", "items": { "description": "Structured tags item details for this tags.", "properties": { "canonical": { "description": "Canonical associated with this tags item; preserve server-returned values when passing them to another operation.", "type": "string" }, "match": { "description": "Match associated with this tags item; preserve server-returned values when passing them to another operation. Supported values: `EXACT`, `ALIAS`, `HEURISTIC`.", "enum": [ "EXACT", "ALIAS", "HEURISTIC" ], "type": "string" }, "raw": { "description": "Original token fragment, retaining inline weighting and artist markers.\nOuter wrappers shared by multi-tag attention groups may be omitted.\n", "type": "string" }, "source": { "description": "Source associated with this tags item; preserve server-returned values when passing them to another operation. Supported values: `ACTIVATION`, `CATALOG`, `SEMANTIC`, `HEURISTIC`.", "enum": [ "ACTIVATION", "CATALOG", "SEMANTIC", "HEURISTIC" ], "type": "string" } }, "required": [ "raw", "canonical", "source", "match" ], "type": "object" }, "type": "array" } }, "required": [ "key", "label", "tags" ], "type": "object" }, "type": "array" }, "summary": { "description": "Structured summary details for this 200 response for api images id prompt analysis.", "properties": { "descriptionCount": { "description": "Number of description records represented by this summary.", "type": "integer" }, "tagCount": { "description": "Number of tag records represented by this summary.", "type": "integer" }, "unclassifiedCount": { "description": "Number of unclassified records represented by this summary.", "type": "integer" } }, "required": [ "tagCount", "descriptionCount", "unclassifiedCount" ], "type": "object" } }, "required": [ "analyzerVersion", "dialect", "description", "groups", "summary" ], "type": "object" } } }, "description": "Grouped positive-prompt analysis.", "headers": { "Cache-Control": { "description": "Private, non-cacheable response because prompts may be owner-visible.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Image ID must be a positive integer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or not visible to the current viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Group an image prompt by semantic category", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/prompt-analysis' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/prompt-analysis', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/prompt-analysis',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{id}/publish": { "post": { "description": "Publish a caller-managed image immediately and apply the normal visibility, notification, and audit workflow. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "publishImage", "parameters": [ { "description": "ID of the image to publish.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Image published.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not allowed to publish this image.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Publish an image immediately", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/123/publish' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/publish', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/123/publish',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/reactions": { "delete": { "description": "Remove the current caller’s reaction from a visible image. The final state is stable when the request is repeated after an ambiguous response.", "operationId": "removeImageReaction", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Reaction removed" }, "schema": { "$ref": "#/components/schemas/DeveloperImageReactionResponse" } } }, "description": "Reaction removed successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove the user's reaction from an image", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/images/123/reactions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/reactions', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/images/123/reactions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "post": { "description": "Set or replace the current caller’s reaction on a visible image. Sending the same reaction again leaves the resource in the same state.", "operationId": "setImageReaction", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "reactionType": "heart" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "reactionType": { "description": "The type of reaction (heart, like, or dislike).", "enum": [ "heart", "like", "dislike" ], "type": "string" } }, "required": [ "reactionType" ], "type": "object" } } }, "description": "Reaction type to apply.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "imageId": 108, "message": "Reaction updated" }, "schema": { "$ref": "#/components/schemas/DeveloperImageReactionResponse" } } }, "description": "Reaction updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Add or update a reaction to an image", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/123/reactions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"reactionType\":\"heart\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/reactions', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"reactionType\": \"heart\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/123/reactions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"reactionType\\\":\\\"heart\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "social-reaction", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/related": { "get": { "description": "List images related to one visible source image while applying publication, ownership, rating, and adult-content rules for the current caller to every returned record.", "operationId": "listRelatedImages", "parameters": [ { "description": "ID of the reference image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" } ], "schema": { "description": "Ordered 200 response for api images id related values returned by this operation.", "items": { "$ref": "#/components/schemas/Image" }, "type": "array" } } }, "description": "List of related images.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve images related to a given image", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/related' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/related', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/related',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{id}/report": { "post": { "description": "Report one image for moderation. Reuse an Idempotency-Key for safe retries; a caller’s existing report returns 204 and no response body.", "operationId": "reportImage", "parameters": [ { "description": "ID of the image to report.", "example": 108, "in": "path", "name": "id", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Content reported successfully" }, "schema": { "$ref": "#/components/schemas/DeveloperReportResponse" } } }, "description": "Image reported successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "204": { "description": "You have already reported this image.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Image already moderated and cannot be reported. The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Report an image", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/123/report' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/report', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/123/report',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "report-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/images/{id}/schedule": { "post": { "description": "Schedule a caller-managed image for a future publication time supplied as an ISO-8601 timestamp. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "scheduleImage", "parameters": [ { "description": "ID of the image to schedule.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "publishAt": "2026-07-28T10:00:00.000Z" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "publishAt": { "description": "Timestamp when the image should be published.", "format": "date-time", "type": "string" } }, "required": [ "publishAt" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Image scheduled.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid publish date.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to schedule this image.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Schedule publishing of an image", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/123/schedule' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"publishAt\":\"2026-07-28T10:00:00.000Z\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/schedule', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"publishAt\": \"2026-07-28T10:00:00.000Z\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/123/schedule',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"publishAt\\\":\\\"2026-07-28T10:00:00.000Z\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/showcased": { "patch": { "description": "Set the explicit showcased state for a caller-owned image while enforcing the per-profile showcase limit. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "setImageShowcase", "parameters": [ { "description": "ID of the image to showcase.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "showcased": "NONE" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "showcased": { "description": "Showcase placement for the image.", "enum": [ "NONE", "PROFILE" ], "type": "string" } }, "required": [ "showcased" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Showcase state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid showcased value, limit exceeded, or missing payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to update showcase for this image.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Showcase or remove showcase from an image", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/images/123/showcased' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"showcased\":\"NONE\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/showcased', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"showcased\": \"NONE\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/images/123/showcased',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"showcased\\\":\\\"NONE\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/spatial-attribution": { "get": { "description": "Return the asynchronous spatial tag-attribution state and visible result for an image. Callers can poll this safe read while respecting Retry-After and the shared read limit.", "operationId": "getImageSpatialAttribution", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "algorithmVersion": "value", "atlasUrl": "value", "columns": 1, "completedAt": "2026-07-28T10:00:00.000Z", "device": "cuda", "durationMs": 1, "height": 1, "mapSize": 1, "message": "value", "modelVersion": "value", "requestAccess": { "accessTier": "ANONYMOUS", "canRequest": true, "freeLimit": 1, "reason": "AUTH_REQUIRED", "remaining": 1 }, "requestedAt": "2026-07-28T10:00:00.000Z", "retryAfterMs": 1, "rows": 1, "status": "disabled", "tags": [ { "distribution": "localized", "focus": 1, "index": 1, "name": "value", "score": 1 } ], "width": 1 }, "schema": { "$ref": "#/components/schemas/ImageSpatialAttribution" } } }, "description": "Current analysis status or a completed tag-location manifest.", "headers": { "Cache-Control": { "description": "Private, non-cacheable response because visibility is viewer-specific.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or not visible to the current viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve the asynchronous tag-location analysis status", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/spatial-attribution' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/spatial-attribution', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/spatial-attribution',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Return an existing spatial-attribution result or enqueue the bounded analysis job once when it is not ready. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "requestImageSpatialAttribution", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "algorithmVersion": "value", "atlasUrl": "value", "columns": 1, "completedAt": "2026-07-28T10:00:00.000Z", "device": "cuda", "durationMs": 1, "height": 1, "mapSize": 1, "message": "value", "modelVersion": "value", "requestAccess": { "accessTier": "ANONYMOUS", "canRequest": true, "freeLimit": 1, "reason": "AUTH_REQUIRED", "remaining": 1 }, "requestedAt": "2026-07-28T10:00:00.000Z", "retryAfterMs": 1, "rows": 1, "status": "disabled", "tags": [ { "distribution": "localized", "focus": 1, "index": 1, "name": "value", "score": 1 } ], "width": 1 }, "schema": { "$ref": "#/components/schemas/ImageSpatialAttribution" } } }, "description": "A current analysis is already ready.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "algorithmVersion": "value", "atlasUrl": "value", "columns": 1, "completedAt": "2026-07-28T10:00:00.000Z", "device": "cuda", "durationMs": 1, "height": 1, "mapSize": 1, "message": "value", "modelVersion": "value", "requestAccess": { "accessTier": "ANONYMOUS", "canRequest": true, "freeLimit": 1, "reason": "AUTH_REQUIRED", "remaining": 1 }, "requestedAt": "2026-07-28T10:00:00.000Z", "retryAfterMs": 1, "rows": 1, "status": "disabled", "tags": [ { "distribution": "localized", "focus": 1, "index": 1, "name": "value", "score": 1 } ], "width": 1 }, "schema": { "$ref": "#/components/schemas/ImageSpatialAttribution" } } }, "description": "Analysis is queued or already processing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication is required to start a new analysis.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "The standard account's free analysis has already been used.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or not visible to the current viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "description": "Tag-location analysis is disabled.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Request a background tag-location analysis", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesWrite", "x-api-key-required-scope-mask": 64, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/123/spatial-attribution' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/spatial-attribution', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/123/spatial-attribution',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/images/{id}/spatial-attribution/atlas": { "get": { "description": "Transfer the generated PNG heatmap atlas for an accessible spatial-attribution result. The endpoint returns binary image content and does not expose unavailable private analyses.", "operationId": "getImageSpatialAttributionAtlas", "parameters": [ { "description": "Unique identifier of the image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "image/png": { "schema": { "description": "200 response for api images id spatial attribution atlas value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Grayscale tag-location atlas.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image or current atlas not found, or the image is not visible to the current viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve the private tag-location heatmap atlas", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/spatial-attribution/atlas' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/spatial-attribution/atlas', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/spatial-attribution/atlas',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{id}/style-matches": { "get": { "description": "Return style-similar visible images and similarity metadata for one source image. A temporary 503 indicates that the similarity index is unavailable and is safe to retry with backoff.", "operationId": "listImageStyleMatches", "parameters": [ { "description": "ID of the reference image.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "Number of matches to return.", "example": 8, "in": "query", "name": "limit", "schema": { "default": 8, "description": "Limit value documented for this operation. Maximum: 50.", "maximum": 50, "type": "integer" } }, { "description": "Optional style matcher backend override.", "example": "example-backend", "in": "query", "name": "backend", "schema": { "description": "Backend value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "matches": [ { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" } ], "meta": {} }, "schema": { "description": "Fields describing 200 response for api images id style matches in Developer API requests and responses.", "properties": { "matches": { "description": "Ordered matches entries included with this 200 response for api images id style matches; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Image" }, "type": "array" }, "meta": { "description": "Structured meta details for this 200 response for api images id style matches.", "type": "object" } }, "type": "object" } } }, "description": "Hydrated style matches and metadata.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid image or file path.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or not visible to the caller.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "description": "Style matcher is temporarily saturated. Retry-After indicates when to retry.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "description": "Style matcher unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve style-similar images for a given image.", "tags": [ "Images" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/style-matches' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/style-matches', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/style-matches',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/images/{imageId}/comments": { "get": { "description": "List comments visible on one image without requiring a write-capable credential. Image visibility and moderation rules are applied before any comment records are returned.", "operationId": "listImageComments", "parameters": [ { "description": "ID of the image.", "example": 1, "in": "path", "name": "imageId", "required": true, "schema": { "description": "Image Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" } ], "schema": { "items": { "$ref": "#/components/schemas/DeveloperComment" }, "type": "array" } } }, "description": "Returns an array of comments.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get all comments for a specific image", "tags": [ "Comments" ], "x-api-key-required-scope": "ImagesRead", "x-api-key-required-scope-mask": 32, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/images/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/comments', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/images/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a comment on a visible image. Reuse the same Idempotency-Key and payload for retries; changing the payload for a used key returns a conflict.", "operationId": "createImageComment", "parameters": [ { "description": "ID of the image to comment on.", "example": 1, "in": "path", "name": "imageId", "required": true, "schema": { "description": "Image Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" }, "parentComment": { "example": null, "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "content" ], "type": "object" } } }, "description": "Comment text and optional parent comment.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment created" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment created successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a comment on an image", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/images/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/comments', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/images/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "social-comment-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/images/{imageId}/comments/{commentId}": { "delete": { "description": "Delete a caller-owned comment from an image. The operation is classified as idempotent, although a repeated call may report that the record is gone.", "operationId": "deleteImageComment", "parameters": [ { "description": "ID of the image.", "example": 1, "in": "path", "name": "imageId", "required": true, "schema": { "description": "Image Id value documented for this operation.", "type": "integer" } }, { "description": "ID of the comment to delete.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Comment deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a comment on an image", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/images/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/comments/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/images/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Replace the editable content of the caller-owned image comment. The target image and comment relationship are both validated before mutation.", "operationId": "updateImageComment", "parameters": [ { "description": "ID of the image.", "example": 1, "in": "path", "name": "imageId", "required": true, "schema": { "description": "Image Id value documented for this operation.", "type": "integer" } }, { "description": "ID of the comment to update.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" } } }, "description": "Replacement comment text.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment updated" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update an existing comment on an image", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/images/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/images/123/comments/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/images/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/model-version-uploads": { "post": { "description": "Create a 24-hour resumable upload session and negotiate chunk sizing for one new hosted model version. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "createModelVersionUpload", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "aboutThisVersion": "Improved natural-light rendering.", "activationTags": "landscape, natural light", "baseModel": "SDXL 1.0", "chunkSize": 8388608, "fileName": "landscape-v2.safetensors", "fileSize": 16777216, "modelId": 42, "supporterEarlyAccessEnabled": true, "versionName": "Landscape v2" }, "schema": { "$ref": "#/components/schemas/CreateModelVersionChunkUploadRequest" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "chunkSize": 8388608, "createdAt": "2026-07-28T10:00:00.000Z", "error": null, "expiresAt": "2026-07-29T10:00:00.000Z", "fileSize": 16777216, "modelId": 42, "originalName": "landscape-v2.safetensors", "receivedBytes": 0, "receivedChunks": [], "status": "created", "totalChunks": 2, "updatedAt": "2026-07-28T10:00:00.000Z", "uploadId": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "versionId": null }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadSession" } } }, "description": "Upload session created. Use the returned `chunkSize`, `totalChunks`, and `uploadId`.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/ModelVersionChunkUploadBadRequest" }, "401": { "$ref": "#/components/responses/ModelVersionChunkUploadUnauthorized" }, "403": { "$ref": "#/components/responses/ModelVersionChunkUploadForbidden" }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/ModelVersionChunkUploadQuotaExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Start a chunked model version upload", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/model-version-uploads' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"modelId\":42,\"fileName\":\"landscape-v2.safetensors\",\"fileSize\":16777216,\"chunkSize\":8388608,\"versionName\":\"Landscape v2\",\"baseModel\":\"SDXL 1.0\",\"aboutThisVersion\":\"Improved natural-light rendering.\",\"activationTags\":\"landscape, natural light\",\"supporterEarlyAccessEnabled\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/model-version-uploads', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"modelId\": 42,\n \"fileName\": \"landscape-v2.safetensors\",\n \"fileSize\": 16777216,\n \"chunkSize\": 8388608,\n \"versionName\": \"Landscape v2\",\n \"baseModel\": \"SDXL 1.0\",\n \"aboutThisVersion\": \"Improved natural-light rendering.\",\n \"activationTags\": \"landscape, natural light\",\n \"supporterEarlyAccessEnabled\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/model-version-uploads',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"modelId\\\":42,\\\"fileName\\\":\\\"landscape-v2.safetensors\\\",\\\"fileSize\\\":16777216,\\\"chunkSize\\\":8388608,\\\"versionName\\\":\\\"Landscape v2\\\",\\\"baseModel\\\":\\\"SDXL 1.0\\\",\\\"aboutThisVersion\\\":\\\"Improved natural-light rendering.\\\",\\\"activationTags\\\":\\\"landscape, natural light\\\",\\\"supporterEarlyAccessEnabled\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/model-version-uploads/{uploadId}": { "delete": { "description": "Cancel the caller’s resumable model-version upload session and discard its staged chunks before completion. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "cancelModelVersionUpload", "parameters": [ { "$ref": "#/components/parameters/ModelVersionChunkUploadId" } ], "responses": { "200": { "content": { "application/json": { "example": { "chunkSize": 8388608, "createdAt": "2026-07-28T10:00:00.000Z", "error": "value", "expiresAt": "2026-07-28T10:00:00.000Z", "fileSize": 1, "modelId": 1, "originalName": "value", "receivedBytes": 1, "receivedChunks": [ 1 ], "status": "created", "totalChunks": 1, "updatedAt": "2026-07-28T10:00:00.000Z", "uploadId": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "versionId": 1 }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadSession" } } }, "description": "Upload session cancelled.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/ModelVersionChunkUploadUnauthorized" }, "403": { "$ref": "#/components/responses/ModelVersionChunkUploadForbidden" }, "404": { "$ref": "#/components/responses/ModelVersionChunkUploadNotFound" }, "409": { "content": { "application/json": { "example": { "error": "Upload session is already completed" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "The upload session is already completed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Cancel a chunked upload session", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/model-version-uploads/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/model-version-uploads/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/model-version-uploads/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Inspect the authenticated caller’s resumable model-version upload session, negotiated chunk size, progress, expiry, and completion state. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "getModelVersionUpload", "parameters": [ { "$ref": "#/components/parameters/ModelVersionChunkUploadId" } ], "responses": { "200": { "content": { "application/json": { "example": { "chunkSize": 8388608, "createdAt": "2026-07-28T10:00:00.000Z", "error": "value", "expiresAt": "2026-07-28T10:00:00.000Z", "fileSize": 1, "modelId": 1, "originalName": "value", "receivedBytes": 1, "receivedChunks": [ 1 ], "status": "created", "totalChunks": 1, "updatedAt": "2026-07-28T10:00:00.000Z", "uploadId": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "versionId": 1 }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadSession" } } }, "description": "Current upload session status.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/ModelVersionChunkUploadUnauthorized" }, "403": { "$ref": "#/components/responses/ModelVersionChunkUploadForbidden" }, "404": { "$ref": "#/components/responses/ModelVersionChunkUploadNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Get chunked upload session status", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/model-version-uploads/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/model-version-uploads/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/model-version-uploads/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/model-version-uploads/{uploadId}/chunks/{index}": { "put": { "description": "Store one indexed binary chunk at the negotiated length; repeating the same index and bytes leaves the upload session unchanged. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadModelVersionChunk", "parameters": [ { "$ref": "#/components/parameters/ModelVersionChunkUploadId" }, { "description": "Zero-based chunk index; must be less than the session's `totalChunks`.", "example": 0, "in": "path", "name": "index", "required": true, "schema": { "description": "Index value documented for this operation. Minimum: 0.", "minimum": 0, "type": "integer" } } ], "requestBody": { "content": { "application/octet-stream": { "example": "example", "schema": { "description": "Request payload value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "chunkSize": 8388608, "createdAt": "2026-07-28T10:00:00.000Z", "error": "value", "expiresAt": "2026-07-28T10:00:00.000Z", "fileSize": 1, "modelId": 1, "originalName": "value", "receivedBytes": 1, "receivedChunks": [ 1 ], "status": "created", "totalChunks": 1, "updatedAt": "2026-07-28T10:00:00.000Z", "uploadId": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "versionId": 1 }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadSession" } } }, "description": "Chunk stored or safely replaced.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "content": { "application/json": { "example": { "error": "Chunk 0 must be 8388608 bytes" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "Missing body, out-of-range index, or body length does not exactly match the expected chunk length.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/ModelVersionChunkUploadUnauthorized" }, "403": { "$ref": "#/components/responses/ModelVersionChunkUploadForbidden" }, "404": { "$ref": "#/components/responses/ModelVersionChunkUploadNotFound" }, "408": { "$ref": "#/components/responses/ModelVersionChunkUploadInterrupted" }, "409": { "content": { "application/json": { "example": { "error": "Chunk 0 must be 8388608 bytes", "errorCode": "UPLOAD_CHUNK_ABORTED", "retryable": true }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "The upload session is already processing or completed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "410": { "$ref": "#/components/responses/ModelVersionChunkUploadCancelled" }, "413": { "content": { "application/json": { "example": { "error": "Chunk 0 must be 8388608 bytes", "errorCode": "UPLOAD_CHUNK_ABORTED", "retryable": true }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "Chunk request exceeds the upload host's request-body limit.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Upload one model version file chunk", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PUT \\\n --url 'https://arcenciel.io/api/model-version-uploads/123/chunks/value' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/model-version-uploads/123/chunks/value', {\n method: 'PUT',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PUT',\n 'https://arcenciel.io/api/model-version-uploads/123/chunks/value',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/model-version-uploads/{uploadId}/complete": { "post": { "description": "Finalize a complete resumable upload session or return its asynchronous processing state without creating a second version. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "completeModelVersionUpload", "parameters": [ { "$ref": "#/components/parameters/ModelVersionChunkUploadId" } ], "responses": { "200": { "content": { "application/json": { "example": { "chunkSize": 8388608, "createdAt": "2026-07-28T10:00:00.000Z", "error": "value", "expiresAt": "2026-07-28T10:00:00.000Z", "fileSize": 1, "modelId": 1, "originalName": "value", "receivedBytes": 1, "receivedChunks": [ 1 ], "status": "created", "totalChunks": 1, "updatedAt": "2026-07-28T10:00:00.000Z", "uploadId": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "versionId": 1 }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadSession" } } }, "description": "Upload was already completed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "chunkSize": 8388608, "createdAt": "2026-07-28T10:00:00.000Z", "error": null, "expiresAt": "2026-07-29T10:00:00.000Z", "fileSize": 16777216, "modelId": 42, "originalName": "landscape-v2.safetensors", "receivedBytes": 16777216, "receivedChunks": [ 0, 1 ], "status": "processing", "totalChunks": 2, "updatedAt": "2026-07-28T10:06:00.000Z", "uploadId": "2f1cdb84-c3a7-4e6c-a289-34bb21e7bd71", "versionId": null }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadSession" } } }, "description": "All chunks were accepted and version creation is processing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "content": { "application/json": { "example": { "error": "Missing upload chunk 1" }, "schema": { "$ref": "#/components/schemas/ModelVersionChunkUploadError" } } }, "description": "At least one expected chunk is missing or assembled bytes do not match `fileSize`.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/ModelVersionChunkUploadUnauthorized" }, "403": { "$ref": "#/components/responses/ModelVersionChunkUploadForbidden" }, "404": { "$ref": "#/components/responses/ModelVersionChunkUploadNotFound" }, "410": { "$ref": "#/components/responses/ModelVersionChunkUploadCancelled" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Complete a chunked model version upload", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/model-version-uploads/123/complete' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/model-version-uploads/123/complete', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/model-version-uploads/123/complete',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models": { "post": { "description": "Create an empty caller-owned model container with validated type, title, description, tags, and author wishes. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "createModel", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "authorWishes": "example", "description": "example", "tags": "example", "title": "example", "type": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "authorWishes": { "description": "JSON array of author wishes.", "type": "string" }, "description": { "description": "Sanitized rich HTML model description. Legacy Markdown or mixed Civitai-style HTML is accepted for compatibility and rendered by the rich-content pipeline.", "type": "string" }, "tags": { "description": "Comma-separated list of tags.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" }, "type": { "description": "The model type (e.g., LORA, CHECKPOINT).", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "message": "Empty model created", "modelId": 52 }, "schema": { "$ref": "#/components/schemas/DeveloperModelCreatedResponse" } } }, "description": "Model created successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a new model draft", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/models/classes": { "get": { "description": "List the model classes currently available for catalogue filtering and model metadata so integrations can discover supported values instead of hard-coding them.", "operationId": "listModelClasses", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "classes": [ { "id": 1, "name": "value" } ] }, "schema": { "description": "Fields describing 200 response for api models classes in Developer API requests and responses.", "properties": { "classes": { "description": "Ordered classes entries included with this 200 response for api models classes; an empty list means none are available.", "items": { "description": "Structured classes item details for this classes.", "properties": { "id": { "description": "Stable identifier for the classes item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "name": { "description": "Human-readable name for this classes item; it is not a stable identifier.", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Model classes", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List available model classes", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/classes' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/classes', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/classes',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/search": { "get": { "description": "Search the public model catalogue with pagination and optional filters. Authentication is optional; account-specific self filters require a valid user session or API key.", "operationId": "searchModels", "parameters": [ { "description": "Search query applied to model title, description, and tags (supports", "example": "landscape", "in": "query", "name": "search", "schema": { "description": "Search value documented for this operation.", "type": "string" } }, { "description": "Sort order for models (hot = recent models sorted by downloads).", "example": "newest", "in": "query", "name": "sort", "schema": { "description": "Sort value documented for this operation. Supported values: `newest`, `oldest`, `downloads`, `favorites`, `hot`.", "enum": [ "newest", "oldest", "downloads", "favorites", "hot" ], "type": "string" } }, { "description": "Page number.", "example": 1, "in": "query", "name": "page", "schema": { "default": 1, "description": "Page value documented for this operation.", "type": "integer" } }, { "description": "Number of models per page (max 1000).", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "description": "Limit value documented for this operation.", "type": "integer" } }, { "description": "If present, the search will be treated as a partial model hash.", "example": false, "in": "query", "name": "hashOnly", "schema": { "default": false, "description": "Hash Only value documented for this operation.", "type": "boolean" } }, { "description": "Filter models by base model.", "example": "example-base-model", "in": "query", "name": "baseModel", "schema": { "description": "Base Model value documented for this operation.", "type": "string" } }, { "description": "Filter models by model type (e.g. LORA, CHECKPOINT, etc.).", "example": "example-model-type", "in": "query", "name": "modelType", "schema": { "description": "Model Type value documented for this operation.", "type": "string" } }, { "description": "Filter models by uploader id.", "example": 1, "in": "query", "name": "userId", "schema": { "description": "User Id value documented for this operation.", "type": "integer" } }, { "description": "Filter by publication status (published = available).", "example": "all", "in": "query", "name": "status", "schema": { "description": "Status value documented for this operation. Supported values: `all`, `available`, `upcoming`.", "enum": [ "all", "available", "upcoming" ], "type": "string" } }, { "description": "Return a lightweight response for template pickers/autocomplete UIs (still respects visibility rules). Compact responses omit download metadata such as hashes, file names, and external download URLs; fetch model or version details before downloading.", "example": false, "in": "query", "name": "compact", "schema": { "default": false, "description": "Compact value documented for this operation.", "type": "boolean" } }, { "description": "Compact only. Max versions returned per model (1-50).", "example": 1, "in": "query", "name": "versionLimit", "schema": { "default": 1, "description": "Version Limit value documented for this operation.", "type": "integer" } }, { "description": "Compact only. Include model.description in results.", "example": false, "in": "query", "name": "includeDescription", "schema": { "default": false, "description": "Include Description value documented for this operation.", "type": "boolean" } }, { "description": "Compact only. Include model.tags in results.", "example": false, "in": "query", "name": "includeTags", "schema": { "default": false, "description": "Include Tags value documented for this operation.", "type": "boolean" } }, { "description": "Compact only. Include model.authorWishes in results.", "example": false, "in": "query", "name": "includeAuthorWishes", "schema": { "default": false, "description": "Include Author Wishes value documented for this operation.", "type": "boolean" } }, { "description": "Auth only. Return models favorited by the current user.", "example": true, "in": "query", "name": "selfFavorited", "schema": { "description": "Self Favorited value documented for this operation.", "type": "boolean" } }, { "description": "Auth only. Return models uploaded by users the current user follows.", "example": true, "in": "query", "name": "selfFollowing", "schema": { "description": "Self Following value documented for this operation.", "type": "boolean" } }, { "description": "Auth only. Return models downloaded by the current user.", "example": true, "in": "query", "name": "selfDownloaded", "schema": { "description": "Self Downloaded value documented for this operation.", "type": "boolean" } }, { "description": "Auth only. Return models not yet downloaded by the current user.", "example": true, "in": "query", "name": "selfNotDownloaded", "schema": { "description": "Self Not Downloaded value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "description": "

Overview

This is an example model.

", "descriptionImages": [], "id": 1, "tags": [ { "id": 1, "name": "example" } ], "title": "Example Model", "type": "LORA", "uploader": { "email": "user@example.com", "id": 2, "username": "exampleUser" }, "uploaderId": 2, "versions": [] } ], "limit": 1, "page": 1, "showcased": [ { "description": "

Overview

This is an example model.

", "descriptionImages": [], "id": 1, "tags": [ { "id": 1, "name": "example" } ], "title": "Example Model", "type": "LORA", "uploader": { "email": "user@example.com", "id": 2, "username": "exampleUser" }, "uploaderId": 2, "versions": [] } ], "totalCount": 1, "totalPages": 1 }, "schema": { "description": "Fields describing 200 response for api models search in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api models search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Model" }, "type": "array" }, "limit": { "description": "Maximum number of records requested or returned in one page of this 200 response for api models search.", "type": "integer" }, "page": { "description": "One-based result page requested or returned for this 200 response for api models search.", "type": "integer" }, "showcased": { "description": "Ordered showcased entries included with this 200 response for api models search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Model" }, "type": "array" }, "totalCount": { "description": "Total number of matching records across all pages for this 200 response for api models search.", "type": "integer" }, "totalPages": { "description": "Total number of pages available at the current page size for this 200 response for api models search.", "type": "integer" } }, "type": "object" } } }, "description": "A paginated list of models.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search models with filtering and pagination", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/search' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/search', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/search',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 300, "policyId": "model-search", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{id}": { "delete": { "description": "Delete an empty caller-managed model after verifying it has no remaining versions or protected relationships. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "deleteModel", "parameters": [ { "description": "Unique identifier of the model.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Model deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the model owner or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a model", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsDelete", "x-api-key-required-scope-mask": 16, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/models/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/models/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one visible model and its accessible version metadata. Anonymous callers receive only public content; owners and staff may receive additional private fields.", "operationId": "getModel", "parameters": [ { "description": "Unique identifier of the model.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "description": "

Overview

This is an example model.

", "descriptionImages": [], "id": 1, "tags": [ { "id": 1, "name": "example" } ], "title": "Example Model", "type": "LORA", "uploader": { "email": "user@example.com", "id": 2, "username": "exampleUser" }, "uploaderId": 2, "versions": [] }, "schema": { "$ref": "#/components/schemas/Model" } } }, "description": "Model details retrieved successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve model details by ID", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update supported model metadata, description, type, tags, and author wishes for a caller-managed model. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateModel", "parameters": [ { "description": "Unique identifier of the model.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "authorWishes": "value", "description": "value", "tags": "value", "title": "value", "type": "value" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "authorWishes": { "description": "JSON array of author wishes.", "type": "string" }, "description": { "description": "Sanitized rich HTML model description. Legacy Markdown or mixed Civitai-style HTML is accepted for compatibility and rendered by the rich-content pipeline.", "type": "string" }, "tags": { "description": "Tags associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of request payload; clients should tolerate future values.", "type": "string" } }, "type": "object" } } }, "description": "Fields to update in the model (title, description, tags, etc.).", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Model updated successfully", "model": { "description": "

Overview

This is an example model.

", "descriptionImages": [], "id": 1, "tags": [ { "id": 1, "name": "example" } ], "title": "Example Model", "type": "LORA", "uploader": { "email": "user@example.com", "id": 2, "username": "exampleUser" }, "uploaderId": 2, "versions": [] } }, "schema": { "$ref": "#/components/schemas/DeveloperModelMutationResponse" } } }, "description": "Model updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the model owner or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Edit an existing model", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"title\":\"value\",\"description\":\"value\",\"tags\":\"value\",\"type\":\"value\",\"authorWishes\":\"value\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"title\": \"value\",\n \"description\": \"value\",\n \"tags\": \"value\",\n \"type\": \"value\",\n \"authorWishes\": \"value\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"title\\\":\\\"value\\\",\\\"description\\\":\\\"value\\\",\\\"tags\\\":\\\"value\\\",\\\"type\\\":\\\"value\\\",\\\"authorWishes\\\":\\\"value\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{id}/description-images": { "post": { "description": "Upload validated inline description images to a caller-managed model and report partial validation outcomes. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadModelDescriptionImages", "parameters": [ { "description": "Unique identifier of the model.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "imageFiles": [ "example" ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "imageFiles": { "description": "JPEG, PNG, or WebP image files, up to 50MB each.", "items": { "description": "Image Files item associated with this image files; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "maxItems": 10, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "images": [ { "filePath": "uploads/images/108.webp", "id": 108 } ] }, "schema": { "$ref": "#/components/schemas/DeveloperStoredImagesUploadResponse" } } }, "description": "Model description images uploaded successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "images": [ { "filePath": "uploads/images/108.webp", "id": 108 } ] }, "schema": { "$ref": "#/components/schemas/DeveloperStoredImagesUploadResponse" } } }, "description": "Some files were invalid but at least one image was uploaded.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request, invalid model id, unsupported file type, or upload limit exceeded.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the model owner or staff).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload images for a model description", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/description-images' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/description-images', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/description-images',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/models/{id}/description-images/{imageId}": { "get": { "description": "Transfer one description image belonging to a visible model after applying model and image visibility rules. Clients must use the returned Content-Type instead of assuming a file format.", "operationId": "getModelDescriptionImage", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "Image Id provided in the path.", "example": 1, "in": "path", "name": "imageId", "required": true, "schema": { "description": "Image Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "description": "200 response for api models id description images image Id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/png": { "schema": { "description": "200 response for api models id description images image Id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/webp": { "schema": { "description": "200 response for api models id description images image Id value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Model description image file.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model or image id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Image not found or not visible to the viewer.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve a model description image", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/description-images/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/description-images/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/description-images/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{id}/favorited": { "patch": { "description": "Set the current caller’s favorite state for a visible model using an explicit boolean. Repeating the same desired state cannot reverse the result.", "operationId": "setModelFavorite", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "favorite": true }, "schema": { "properties": { "favorite": { "description": "The desired favorite state.", "example": true, "type": "boolean" } }, "required": [ "favorite" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Favorite state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Missing/invalid favorite value or no state change possible.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Favorite or unfavorite a model", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/favorited' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"favorite\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/favorited', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"favorite\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/favorited',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"favorite\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "social-favorite", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{id}/gallery": { "get": { "description": "List gallery images associated with one visible model, optionally filtered to a specific model version. Anonymous callers receive only content they may access.", "operationId": "listModelGalleryImages", "parameters": [ { "description": "Unique identifier of the model.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "Optionally filter gallery images to a specific model version.", "example": 1, "in": "query", "name": "versionId", "required": false, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } }, { "description": "One-based result page. Pinned images are returned only on the first page.", "example": 1, "in": "query", "name": "page", "schema": { "default": 1, "description": "Page value documented for this operation. Minimum: 1. Maximum: 100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Maximum number of mixed image and video entries per page.", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "description": "Limit value documented for this operation. Minimum: 1. Maximum: 30.", "maximum": 30, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "data": { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" }, "kind": "image" } ], "limit": 1, "page": 1, "pinned": [ { "cfg": 7, "createdAt": "2025-01-01T12:00:00Z", "description": "A sample image description.", "dislikeCount": 2, "fileName": "sample.jpg", "filePath": "uploads/images/sample.jpg", "heartCount": 5, "id": 1, "likeCount": 10, "metadata": "EXIF data...", "negativePrompt": "low quality", "prompt": "A beautiful landscape", "rating": "safe", "sampler": "Euler", "seed": 123456789, "steps": 50, "title": "Sample Image", "updatedAt": "2025-01-01T12:00:00Z" } ], "totalCount": 1, "totalPages": 1 }, "schema": { "$ref": "#/components/schemas/ModelGalleryResponse" } } }, "description": "A paginated list of image and video entries associated with the model.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve gallery images associated with a model", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/gallery' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/gallery', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/gallery',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{id}/report": { "post": { "description": "Report another creator’s model with a reason and moderator-facing context. Reuse an Idempotency-Key for retries; resolved targets reject further reports.", "operationId": "reportModel", "parameters": [ { "description": "Model identifier.", "example": 108, "in": "path", "name": "id", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "comment": "This upload impersonates another creator and copies their metadata.", "reason": "MISLEADING", "subReason": "IMPERSONATION" }, "schema": { "properties": { "comment": { "description": "Required moderator-facing context describing the concern.", "example": "This upload impersonates another creator and copies their metadata.", "minLength": 10, "type": "string" }, "reason": { "description": "Primary moderation reason.", "example": "MISLEADING", "minLength": 1, "type": "string" }, "subReason": { "description": "Optional refinement of the primary reason.", "example": "IMPERSONATION", "type": "string" } }, "required": [ "reason", "comment" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Content reported successfully" }, "schema": { "$ref": "#/components/schemas/DeveloperReportResponse" } } }, "description": "Model reported successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "204": { "description": "This user has already reported the model.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model id, missing reason, or comment too short.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Reporting own model is not allowed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Model already moderated; new reports are disabled. The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Report a model for moderation review", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/report' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"reason\":\"MISLEADING\",\"subReason\":\"IMPERSONATION\",\"comment\":\"This upload impersonates another creator and copies their metadata.\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/report', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"reason\": \"MISLEADING\",\n \"subReason\": \"IMPERSONATION\",\n \"comment\": \"This upload impersonates another creator and copies their metadata.\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/report',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"reason\\\":\\\"MISLEADING\\\",\\\"subReason\\\":\\\"IMPERSONATION\\\",\\\"comment\\\":\\\"This upload impersonates another creator and copies their metadata.\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "report-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/models/{id}/showcased": { "patch": { "description": "Set the explicit showcased state for a caller-owned model while enforcing the per-profile showcase limit. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "setModelShowcase", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "showcased": "NONE" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "showcased": { "description": "Showcase placement for the model.", "enum": [ "NONE", "PROFILE" ], "type": "string" } }, "required": [ "showcased" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Showcase state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid showcased value, limit exceeded, or missing payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to modify showcase for this model.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Showcase or unshowcase a model", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/showcased' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"showcased\":\"NONE\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/showcased', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"showcased\": \"NONE\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/showcased',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"showcased\\\":\\\"NONE\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/comments": { "get": { "description": "List comments visible on one model using the domain read scope rather than SocialWrite. The target model must remain visible to the current caller.", "operationId": "listModelComments", "parameters": [ { "description": "The ID of the model.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" } ], "schema": { "items": { "$ref": "#/components/schemas/DeveloperComment" }, "type": "array" } } }, "description": "Returns an array of comments.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List all comments for a specific model", "tags": [ "Comments" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/comments', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a comment on a visible model. Idempotency records are isolated by caller, method, target path, and key and retain successful responses for 24 hours.", "operationId": "createModelComment", "parameters": [ { "description": "The ID of the model.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" }, "parentComment": { "example": null, "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "content" ], "type": "object" } } }, "description": "Comment text and optional parent comment.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment created" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment created successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a comment on a model", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/comments', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "social-comment-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/models/{modelId}/comments/{commentId}": { "delete": { "description": "Delete a caller-owned comment from a model while preserving ownership and target checks. Repeating the deletion cannot recreate the comment.", "operationId": "deleteModelComment", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Comment Id provided in the path.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Comment deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a comment on a model", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/models/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/comments/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/models/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Replace the editable content of the caller-owned model comment. The operation never permits an API key to edit another user’s comment.", "operationId": "updateModelComment", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Comment Id provided in the path.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" } } }, "description": "Replacement comment text.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment updated" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update an existing comment on a model", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/comments/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions": { "get": { "description": "List the versions visible to the caller for one model, including release metadata, file-safety state, hashes, activation tags, and public training metadata when available.", "operationId": "listModelVersions", "parameters": [ { "description": "ID of the model.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "versions": [ { "aboutThisVersion": "Initial release.", "activationTags": [ "tag1", "tag2" ], "baseModel": "SD 1.5", "downloadCount": 10, "externalDownloadUrl": null, "fileName": "model_v1.safetensors", "filePath": "uploads/models/example/model_v1.safetensors", "fileScanEngineVersion": "clamscan --no-summary", "fileScanMeta": { "scanner": "clamav" }, "fileScanReason": null, "fileScanSource": "local_upload", "fileScanStatus": "CLEAN", "fileScannedAt": "2026-03-19T10:00:00.000Z", "fileSizeKb": 131072, "id": 1, "imageOrder": [ 3, 1, 2 ], "images": [], "originalName": "model_v1.safetensors", "publishAt": null, "sha256": "abcdef123456...", "sha256webui": "1234abcd", "status": "PUBLISHED", "supporterEarlyAccessEnabled": true, "trainingMetadataSummary": { "dataset": { "dirs": [ { "imageCount": 128, "name": "cats" } ], "totalImages": 256 }, "extractedAt": "2026-02-19T10:00:00.000Z", "run": { "epoch": 3, "learningRate": 0.0001, "optimizer": "AdamW8bit", "resolution": "1024x1024", "totalEpochs": 10 }, "schemaVersion": 1, "source": "upload_local", "tagsTop": [ { "count": 42, "tag": "cat" } ] }, "versionName": "v1" } ] }, "schema": { "$ref": "#/components/schemas/ModelVersionListResponse" } } }, "description": "Visible version objects wrapped in the stable versions property.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List all versions of a model", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Replace a model’s version ordering with a validated list containing exactly its current version identifiers. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "reorderModelVersions", "parameters": [ { "description": "ID of the model whose versions you want to reorder.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "versionIds": [ 3, 1, 2 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "versionIds": { "description": "The new order of version IDs.", "example": [ 3, 1, 2 ], "items": { "description": "Numeric version ids item reported for this version ids.", "type": "integer" }, "type": "array" } }, "type": "object" } } }, "description": "JSON object with the new order of version IDs.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Versions reordered successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid version IDs or order.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Reorder multiple versions of a model", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/versions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"versionIds\":[3,1,2]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"versionIds\": [\n 3,\n 1,\n 2\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/versions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"versionIds\\\":[3,1,2]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "post": { "description": "Create a model version from one hosted file or one validated external source, including hashes, scan state, and release metadata. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "createModelVersion", "parameters": [ { "description": "ID of the model.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "aboutThisVersion": "example", "activationTags": "example", "baseModel": "example", "huggingfaceLink": "example", "supporterEarlyAccessEnabled": true, "versionFile": "example", "versionName": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "aboutThisVersion": { "description": "About This Version associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "activationTags": { "description": "Activation Tags associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "baseModel": { "description": "Base Model associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "huggingfaceLink": { "description": "URL to a HuggingFace model file. Either versionFile or huggingfaceLink must be provided. Allowed by default: .safetensors, .pt. For models of type OTHER, archive extensions are also allowed.", "type": "string" }, "supporterEarlyAccessEnabled": { "default": true, "description": "Creator opt-out for the 72-hour supporter early-access window. External sources are always excluded.", "type": "boolean" }, "versionFile": { "description": "The file for the model version. Allowed by default: .safetensors, .pt. For models of type OTHER, archives are also allowed (.zip, .7z, .rar, .tar, .tar.gz, .tar.xz, .tar.bz2, .gz, .xz, .bz2).", "format": "binary", "type": "string" }, "versionName": { "description": "Human-readable version name for this request payload; it is not a stable identifier.", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "message": "New version created", "versionId": 321 }, "schema": { "$ref": "#/components/schemas/DeveloperVersionCreatedResponse" } } }, "description": "New version created successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Add a new version to an existing model", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/versions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/versions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/models/{modelId}/versions/download-all": { "get": { "description": "Stream a ZIP archive containing all downloadable files of a visible model. Unavailable or unsafe versions are omitted and described in an archive README when partial output is possible.", "operationId": "downloadAllModelVersions", "parameters": [ { "description": "Model identifier.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/zip": { "schema": { "description": "200 response for api models model Id versions download all value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "ZIP archive stream.", "headers": { "Content-Disposition": { "description": "Attachment disposition containing the generated model archive filename.", "schema": { "example": "attachment; filename=\"model-14474-versions.zip\"", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found or no downloadable files available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Failed to build archive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download all downloadable version files of a model as a ZIP archive", "tags": [ "Downloads" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/download-all' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/download-all', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/download-all',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/media-preview": { "get": { "description": "List lightweight visible image and video previews grouped by selected model versions. Scheduled content is sanitized for non-owners and inaccessible media is excluded from the response.", "operationId": "listModelVersionMediaPreviews", "parameters": [ { "description": "Unique identifier of the model.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Comma-separated list of version IDs to fetch previews for. Defaults to all visible versions.", "example": "example-version-ids", "in": "query", "name": "versionIds", "required": false, "schema": { "description": "Version Ids value documented for this operation.", "type": "string" } }, { "description": "Maximum number of preview entries per version.", "example": 6, "in": "query", "name": "limit", "schema": { "default": 6, "description": "Limit value documented for this operation. Maximum: 12.", "maximum": 12, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "limit": 6, "modelId": 14474, "versions": [ { "entries": [ { "data": { "filePath": "/uploads/images/90321.webp", "height": 1024, "id": 90321, "width": 1024 }, "kind": "image", "origin": "version" } ], "id": 16198 } ] }, "schema": { "$ref": "#/components/schemas/ModelVersionMediaPreviewResponse" } } }, "description": "Preview entries grouped by version.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model id or parameters.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found or inaccessible.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve lightweight carousel media previews for specific model versions", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/media-preview' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/media-preview', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/media-preview',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}": { "delete": { "description": "Delete one caller-managed model version and automatically remove the model only when it was the final version. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "deleteModelVersion", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Version removed successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a model version (soft-delete)", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsDelete", "x-api-key-required-scope-mask": 16, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/models/123/versions/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/models/123/versions/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return one accessible model version, including hashes, file-safety state, activation tags, and public training metadata when those values are available.", "operationId": "getModelVersion", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "aboutThisVersion": "Initial release.", "activationTags": [ "tag1", "tag2" ], "baseModel": "SD 1.5", "downloadCount": 10, "externalDownloadUrl": null, "fileName": "model_v1.safetensors", "filePath": "uploads/models/example/model_v1.safetensors", "fileScanEngineVersion": "clamscan --no-summary", "fileScanMeta": { "scanner": "clamav" }, "fileScanReason": null, "fileScanSource": "local_upload", "fileScanStatus": "CLEAN", "fileScannedAt": "2026-03-19T10:00:00.000Z", "fileSizeKb": 131072, "id": 1, "imageOrder": [ 3, 1, 2 ], "images": [], "originalName": "model_v1.safetensors", "publishAt": null, "sha256": "abcdef123456...", "sha256webui": "1234abcd", "status": "PUBLISHED", "supporterEarlyAccessEnabled": true, "trainingMetadataSummary": { "dataset": { "dirs": [ { "imageCount": 128, "name": "cats" } ], "totalImages": 256 }, "extractedAt": "2026-02-19T10:00:00.000Z", "run": { "epoch": 3, "learningRate": 0.0001, "optimizer": "AdamW8bit", "resolution": "1024x1024", "totalEpochs": 10 }, "schemaVersion": 1, "source": "upload_local", "tagsTop": [ { "count": 42, "tag": "cat" } ] }, "versionName": "v1" }, "schema": { "$ref": "#/components/schemas/Version" } } }, "description": "Version details retrieved successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve details of a specific model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update release metadata, source selection, hashes, file metadata, and early-access settings for a caller-managed model version. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateModelVersion", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "aboutThisVersion": "example", "activationTags": "example", "baseModel": "example", "supporterEarlyAccessEnabled": true, "versionName": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "aboutThisVersion": { "description": "About This Version associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "activationTags": { "description": "Activation Tags associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "baseModel": { "description": "Base Model associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "supporterEarlyAccessEnabled": { "description": "Set false to opt this hosted version out of supporter early access.", "type": "boolean" }, "versionName": { "description": "Human-readable version name for this request payload; it is not a stable identifier.", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Version updated successfully", "version": { "aboutThisVersion": "Initial release.", "activationTags": [ "tag1", "tag2" ], "baseModel": "SD 1.5", "downloadCount": 10, "externalDownloadUrl": null, "fileName": "model_v1.safetensors", "filePath": "uploads/models/example/model_v1.safetensors", "fileScanEngineVersion": "clamscan --no-summary", "fileScanMeta": { "scanner": "clamav" }, "fileScanReason": null, "fileScanSource": "local_upload", "fileScanStatus": "CLEAN", "fileScannedAt": "2026-03-19T10:00:00.000Z", "fileSizeKb": 131072, "id": 1, "imageOrder": [ 3, 1, 2 ], "images": [], "originalName": "model_v1.safetensors", "publishAt": null, "sha256": "abcdef123456...", "sha256webui": "1234abcd", "status": "PUBLISHED", "supporterEarlyAccessEnabled": true, "trainingMetadataSummary": { "dataset": { "dirs": [ { "imageCount": 128, "name": "cats" } ], "totalImages": 256 }, "extractedAt": "2026-02-19T10:00:00.000Z", "run": { "epoch": 3, "learningRate": 0.0001, "optimizer": "AdamW8bit", "resolution": "1024x1024", "totalEpochs": 10 }, "schemaVersion": 1, "source": "upload_local", "tagsTop": [ { "count": 42, "tag": "cat" } ] }, "versionName": "v1" } }, "schema": { "$ref": "#/components/schemas/DeveloperVersionMutationResponse" } } }, "description": "Model version updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Edit an existing model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/versions/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/versions/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions/{versionId}/community-media": { "patch": { "description": "Add or remove one published image or video from a model version’s bounded community-media carousel. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "setModelVersionCommunityMedia", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "include": true, "mediaId": 1, "mediaType": "IMAGE" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "include": { "description": "Set to true to add the media, false to remove it.", "type": "boolean" }, "mediaId": { "description": "Stable identifier for the media; use it in subsequent API calls instead of a display name.", "type": "integer" }, "mediaType": { "description": "Discriminator identifying the kind of request payload; clients should tolerate future values. Supported values: `IMAGE`, `VIDEO`.", "enum": [ "IMAGE", "VIDEO" ], "type": "string" } }, "required": [ "mediaType", "mediaId", "include" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Community media updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid payload or limit reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to modify this version.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version or media not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Add or remove community media for a model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/versions/123/community-media' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"mediaType\":\"IMAGE\",\"mediaId\":1,\"include\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/community-media', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"mediaType\": \"IMAGE\",\n \"mediaId\": 1,\n \"include\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/versions/123/community-media',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"mediaType\\\":\\\"IMAGE\\\",\\\"mediaId\\\":1,\\\"include\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions/{versionId}/download": { "get": { "description": "Download a hosted model file or register an external-only download. Clients must allow documented HTTPS redirects, preserve Range headers, and verify the full SHA-256 hash when provided.", "operationId": "downloadModelVersion", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Download registered (external URL)" }, "schema": { "description": "Fields describing 200 response for api models model id versions version id download in Developer API requests and responses.", "properties": { "message": { "description": "Message associated with this 200 response for api models model id versions version id download; preserve server-returned values when passing them to another operation.", "example": "Download registered (external URL)", "type": "string" } }, "type": "object" } }, "application/octet-stream": { "schema": { "description": "200 response for api models model Id versions version Id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Binary file download for hosted files, or JSON registration response for external-only versions.", "headers": { "Accept-Ranges": { "schema": { "example": "bytes", "type": "string" } }, "Content-Disposition": { "schema": { "type": "string" } }, "X-File-Scan-Reason": { "description": "Present when a scan reason is available.", "schema": { "type": "string" } }, "X-File-Scan-Status": { "schema": { "enum": [ "UNSCANNED", "PENDING", "CLEAN", "POTENTIALLY_RISKY", "INFECTED", "SCAN_ERROR", "UNVERIFIED_EXTERNAL" ], "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "application/octet-stream": { "schema": { "description": "206 response for api models model Id versions version Id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Partial content for a valid byte range request.", "headers": { "Content-Length": { "schema": { "type": "integer" } }, "Content-Range": { "schema": { "type": "string" } }, "X-File-Scan-Status": { "schema": { "enum": [ "UNSCANNED", "PENDING", "CLEAN", "POTENTIALLY_RISKY", "INFECTED", "SCAN_ERROR", "UNVERIFIED_EXTERNAL" ], "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "302": { "description": "Production redirect to the dedicated transfer host for Arc-hosted files.", "headers": { "Location": { "description": "Redirect target on https://uploads.arcenciel.io.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "304": { "description": "Cached file is still fresh.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model/version id, relationship mismatch, or no hosted file path is available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Version is not public and the caller has no applicable early-access entitlement.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found or file not available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "416": { "description": "Requested byte range is not satisfiable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "423": { "content": { "application/json": { "example": { "error": "value" }, "schema": { "description": "Fields describing 423 response for api models model id versions version id download in Developer API requests and responses.", "properties": { "error": { "description": "Error associated with this 423 response for api models model id versions version id download; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" } } }, "description": "File blocked due to malware, unsafe, or scan-error status.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download the model version file", "tags": [ "Downloads" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/download', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/download-info": { "get": { "description": "Inspect the supported download source, filename, hashes, redirect allowlist, file-safety state, and early-access decision before transferring a model file.", "operationId": "getModelVersionDownloadInfo", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "allowedRedirectHosts": [ "uploads.arcenciel.io" ], "available": true, "blocked": false, "downloadUrl": "/api/models/1/versions/2/download/model_v1.safetensors", "earlyAccess": { "canDownload": false, "canDownloadViaLink": false, "enabled": false, "reason": "PUBLIC", "startsAt": null, "state": "PUBLIC", "windowHours": 72 }, "externalDownloadUrl": null, "fileName": "model_v1.safetensors", "fileScanReason": null, "fileScanStatus": "CLEAN", "fileSizeKb": 131072, "modelId": 1, "originalName": "model_v1.safetensors", "registerUrl": "/api/models/1/versions/2/download/register", "sha256": "abcdef123456...", "sha256webui": "1234abcd", "source": "hosted", "status": "PUBLISHED", "versionId": 2 }, "schema": { "$ref": "#/components/schemas/VersionDownloadInfo" } } }, "description": "Download metadata for the version.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model/version id or relationship mismatch.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Version is not published or is scheduled for the future.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "423": { "description": "A scheduled hosted file is not safety-cleared for supporter early access.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Inspect model version download metadata", "tags": [ "Downloads" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/download-info' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/download-info', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/download-info',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/download/register": { "post": { "description": "Record a completed direct or external download without streaming the file through Arc en Ciel. Authentication is optional and associates the event with the caller when available.", "operationId": "registerModelVersionDownload", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "delivery": "external", "message": "value" }, "schema": { "description": "Fields describing 200 response for api models model id versions version id download register in Developer API requests and responses.", "properties": { "delivery": { "description": "Delivery associated with this 200 response for api models model id versions version id download register; preserve server-returned values when passing them to another operation. Supported values: `external`, `local`.", "enum": [ "external", "local" ], "type": "string" }, "message": { "description": "Message associated with this 200 response for api models model id versions version id download register; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" } } }, "description": "Download registration completed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model/version id, relationship mismatch, or no file available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Version is not publicly available and the caller has no applicable early-access entitlement.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found or inaccessible.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "423": { "description": "File blocked due to malware, unsafe, or scan-error status.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Register a model version download without streaming the file", "tags": [ "Downloads" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/versions/123/download/register' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/download/register', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/versions/123/download/register',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/models/{modelId}/versions/{versionId}/download/{downloadName}": { "get": { "description": "Download the selected model version using a client-friendly filename hint. The version identifier selects the file; clients must not treat downloadName as a trusted source of identity.", "operationId": "downloadModelVersionWithFilename", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } }, { "description": "Filename slug used by clients and CDNs; the version id selects the actual file.", "example": "example-download-name", "in": "path", "name": "downloadName", "required": true, "schema": { "description": "Download Name value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Download registered (external URL)" }, "schema": { "description": "Fields describing 200 response for api models model id versions version id download download name in Developer API requests and responses.", "properties": { "message": { "description": "Message associated with this 200 response for api models model id versions version id download download name; preserve server-returned values when passing them to another operation.", "example": "Download registered (external URL)", "type": "string" } }, "type": "object" } }, "application/octet-stream": { "schema": { "description": "200 response for api models model Id versions version Id download download Name value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Binary file download for hosted files, or JSON registration response for external-only versions.", "headers": { "Accept-Ranges": { "schema": { "example": "bytes", "type": "string" } }, "Content-Disposition": { "schema": { "type": "string" } }, "X-File-Scan-Reason": { "description": "Present when a scan reason is available.", "schema": { "type": "string" } }, "X-File-Scan-Status": { "schema": { "enum": [ "UNSCANNED", "PENDING", "CLEAN", "POTENTIALLY_RISKY", "INFECTED", "SCAN_ERROR", "UNVERIFIED_EXTERNAL" ], "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "application/octet-stream": { "schema": { "description": "206 response for api models model Id versions version Id download download Name value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Partial content for a valid byte range request.", "headers": { "Content-Length": { "schema": { "type": "integer" } }, "Content-Range": { "schema": { "type": "string" } }, "X-File-Scan-Status": { "schema": { "enum": [ "UNSCANNED", "PENDING", "CLEAN", "POTENTIALLY_RISKY", "INFECTED", "SCAN_ERROR", "UNVERIFIED_EXTERNAL" ], "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "302": { "description": "Production redirect to the dedicated transfer host for Arc-hosted files.", "headers": { "Location": { "description": "Redirect target on https://uploads.arcenciel.io.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "304": { "description": "Cached file is still fresh.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model/version id, relationship mismatch, or no hosted file path is available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found or file not available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "416": { "description": "Requested byte range is not satisfiable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "423": { "content": { "application/json": { "example": { "error": "value" }, "schema": { "description": "Fields describing 423 response for api models model id versions version id download download name in Developer API requests and responses.", "properties": { "error": { "description": "Error associated with this 423 response for api models model id versions version id download download name; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" } } }, "description": "File blocked due to malware, unsafe, or scan-error status.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download the model version file with a stable filename", "tags": [ "Downloads" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/download/example' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/download/example', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/download/example',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/images": { "patch": { "description": "Replace the sample-image order for a model version after validating the complete set of attached image identifiers. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "reorderModelVersionImages", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "imageIds": [ 3, 1, 2 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "imageIds": { "description": "Array of image IDs representing the new order.", "example": [ 3, 1, 2 ], "items": { "description": "Numeric image ids item reported for this image ids.", "type": "integer" }, "type": "array" } }, "type": "object" } } }, "description": "JSON object with new order of image IDs.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Images reordered successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid image IDs or order.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Reorder images for a specific model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/versions/123/images' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"imageIds\":[3,1,2]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/images', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"imageIds\": [\n 3,\n 1,\n 2\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/versions/123/images',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"imageIds\\\":[3,1,2]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "post": { "description": "Upload validated sample images to a caller-managed model version and preserve accepted identifiers on partial failure. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadModelVersionImages", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "description": "example", "imageFiles": [ "example" ], "tags": "example", "title": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "type": "string" }, "imageFiles": { "description": "Array of image files.", "items": { "description": "Image Files item associated with this image files; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "type": "array" }, "tags": { "description": "Comma-separated list of tags.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" } }, "type": "object" } } }, "description": "Multipart form data containing the images and optional metadata.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "imageIds": [ 108, 109 ] }, "schema": { "$ref": "#/components/schemas/DeveloperImageUploadResponse" } } }, "description": "Version image(s) uploaded successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "imageIds": [ 108, 109 ] }, "schema": { "$ref": "#/components/schemas/DeveloperImageUploadResponse" } } }, "description": "Some images were rejected while the remaining images were stored.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request (e.g. no files uploaded or invalid file format).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Upload one or more images for a specific model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/versions/123/images' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/images', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/versions/123/images',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/models/{modelId}/versions/{versionId}/images/attach": { "post": { "description": "Attach selected hash-matched Discord images to a model version while returning already attached identifiers separately. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "attachModelVersionDiscordImages", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "imageIds": [ 1 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "imageIds": { "description": "Ordered image ids entries included with this request payload; an empty list means none are available.", "items": { "description": "Numeric image ids item reported for this image ids.", "type": "integer" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "imageIds": [ 108 ], "imageOrder": [ 107, 108 ], "message": "Existing Discord images attached to version.", "skippedAlreadyAttachedIds": [ 107 ] }, "schema": { "$ref": "#/components/schemas/DeveloperAttachedImagesResponse" } } }, "description": "Images attached successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid image ids.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Attach Discord-uploaded images to a model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/versions/123/images/attach' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"imageIds\":[1]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/images/attach', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"imageIds\": [\n 1\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/versions/123/images/attach',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"imageIds\\\":[1]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions/{versionId}/images/discord-candidates": { "get": { "description": "List caller-owned Discord uploads whose resource hashes match a model version and indicate which images can be attached without duplication. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "listModelVersionDiscordImageCandidates", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "alreadyAttachedCount": 0, "attachableCount": 1, "items": [ { "disabledReason": null, "id": 108, "isAlreadyAttached": false, "isAttachable": true, "matchedHashes": [ "0123456789abcdef" ] } ], "totalFound": 1 }, "schema": { "$ref": "#/components/schemas/DeveloperDiscordImageCandidatesResponse" } } }, "description": "Candidate images returned successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List Discord-uploaded images that can be attached to a model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/images/discord-candidates' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/images/discord-candidates', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/images/discord-candidates',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/publish": { "post": { "description": "Publish a caller-managed model version immediately after file-safety and lifecycle requirements have passed. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "publishModelVersion", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Version published and followers notified.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Version already published or invalid request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to publish this version.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Publish a model version immediately", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/versions/123/publish' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/publish', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/versions/123/publish',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions/{versionId}/resources": { "get": { "description": "Return detected and curated local or external dependencies for one visible model version. Hidden edges and management metadata are included only for authorized owners and staff.", "operationId": "getModelVersionResources", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "canManage": false, "counts": { "detected": 1, "external": 0, "hidden": 0, "local": 1 }, "groups": { "compatible": [], "external": [], "recommended": [], "required": [ { "baseModel": "SDXL", "confidence": 0.97, "downloadUrl": "/api/models/14475/versions/16200/download", "edgeId": 45, "evidence": { "trigger": "detailer" }, "fileName": "detailer.safetensors", "fileScanStatus": "CLEAN", "fileSizeKb": 128000, "id": 45, "kind": "REQUIRED", "modelId": 14475, "modelType": "LORA", "openUrl": "/models/14475#version-16200", "previewImage": null, "publishAt": "2026-07-01T00:00:00.000Z", "source": "IMAGE_METADATA", "status": "ACTIVE", "strength": 1, "targetType": "local", "title": "Detailer", "versionId": 16200, "versionName": "v1", "versionStatus": "PUBLISHED" } ], "sampleUsed": [] }, "sourceVersionId": 16198 }, "schema": { "$ref": "#/components/schemas/ModelVersionResourceGraphResponse" } } }, "description": "Resource graph grouped by dependency kind.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve detected and manually curated version resource dependencies", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/resources' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/resources', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/resources',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/resources/candidates": { "get": { "description": "Search visible model versions that the caller may add to the managed dependency graph of the selected source version. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "listModelVersionResourceCandidates", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } }, { "description": "Q provided in the query.", "example": "landscape", "in": "query", "name": "q", "schema": { "description": "Q value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "candidates": [ { "downloadUrl": "/api/models/52/versions/321/download", "modelId": 52, "openUrl": "/models/52#version-321", "targetType": "local", "title": "Portrait Detailer", "versionId": 321, "versionName": "v2.0" } ] }, "schema": { "$ref": "#/components/schemas/DeveloperModelVersionResourceCandidatesResponse" } } }, "description": "Candidate version list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search local versions that can be added as manual resources", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/resources/candidates' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/resources/candidates', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/resources/candidates',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/resources/manual": { "put": { "description": "Upsert or replace the manually managed dependency edges for one caller-managed model version and return the complete graph. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "replaceModelVersionResources", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "replace": true, "resources": [ {} ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "replace": { "description": "Whether replace applies to this request payload.", "type": "boolean" }, "resources": { "description": "Ordered resources entries included with this request payload; an empty list means none are available.", "items": { "description": "Structured resources item details for this resources.", "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "canManage": true, "counts": { "detected": 0, "external": 0, "hidden": 0, "local": 0 }, "groups": { "compatible": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ], "external": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "externalResourceId": 1, "id": 1, "kind": "example", "provider": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "url": "https://arcenciel.io/developers" } ], "recommended": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ], "required": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ], "sampleUsed": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ] }, "sourceVersionId": 1 }, "schema": { "$ref": "#/components/schemas/ModelVersionResourceGraphResponse" } } }, "description": "Refreshed resource graph.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Add or replace manually curated version resource dependencies", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PUT \\\n --url 'https://arcenciel.io/api/models/123/versions/123/resources/manual' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"replace\":true,\"resources\":[{}]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/resources/manual', {\n method: 'PUT',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"replace\": true,\n \"resources\": [\n {}\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PUT',\n 'https://arcenciel.io/api/models/123/versions/123/resources/manual',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"replace\\\":true,\\\"resources\\\":[{}]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions/{versionId}/resources/{edgeId}": { "patch": { "description": "Update, hide, restore, or remove one managed dependency edge and return the complete resulting resource graph. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateModelVersionResource", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } }, { "description": "Edge Id provided in the path.", "example": 1, "in": "path", "name": "edgeId", "required": true, "schema": { "description": "Edge Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "kind": "REQUIRED", "status": "ACTIVE" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "kind": { "description": "Kind associated with this request payload; preserve server-returned values when passing them to another operation. Supported values: `REQUIRED`, `RECOMMENDED`, `COMPATIBLE`, `SAMPLE_USED`.", "enum": [ "REQUIRED", "RECOMMENDED", "COMPATIBLE", "SAMPLE_USED" ], "type": "string" }, "status": { "description": "Current lifecycle state of this request payload; clients should tolerate future values. Supported values: `ACTIVE`, `HIDDEN`.", "enum": [ "ACTIVE", "HIDDEN" ], "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "canManage": true, "counts": { "detected": 0, "external": 0, "hidden": 0, "local": 0 }, "groups": { "compatible": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ], "external": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "externalResourceId": 1, "id": 1, "kind": "example", "provider": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "url": "https://arcenciel.io/developers" } ], "recommended": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ], "required": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ], "sampleUsed": [ { "confidence": 1, "edgeId": 1, "evidence": {}, "id": 1, "kind": "example", "modelId": 1, "modelType": "example", "openUrl": "example", "source": "example", "status": "example", "strength": 1, "targetType": "example", "title": "example", "versionId": 1, "versionName": "example", "versionStatus": "example" } ] }, "sourceVersionId": 1 }, "schema": { "$ref": "#/components/schemas/ModelVersionResourceGraphResponse" } } }, "description": "Refreshed resource graph.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Resource edge not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update a resource dependency edge", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/versions/123/resources/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"kind\":\"REQUIRED\",\"status\":\"ACTIVE\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/resources/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"kind\": \"REQUIRED\",\n \"status\": \"ACTIVE\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/versions/123/resources/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"kind\\\":\\\"REQUIRED\\\",\\\"status\\\":\\\"ACTIVE\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions/{versionId}/schedule": { "post": { "description": "Schedule a caller-managed model version for future publication and persist its early-access preference. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "scheduleModelVersion", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "publishAt": "2026-07-28T10:00:00.000Z", "supporterEarlyAccessEnabled": true }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "publishAt": { "description": "Timestamp when the version should be published.", "format": "date-time", "type": "string" }, "supporterEarlyAccessEnabled": { "default": true, "description": "Set false to opt this hosted scheduled version out of supporter early access.", "type": "boolean" } }, "required": [ "publishAt" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Version scheduled.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid publish date.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to schedule this version.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Schedule publishing of a model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/versions/123/schedule' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"publishAt\":\"2026-07-28T10:00:00.000Z\",\"supporterEarlyAccessEnabled\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/schedule', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"publishAt\": \"2026-07-28T10:00:00.000Z\",\n \"supporterEarlyAccessEnabled\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/versions/123/schedule',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"publishAt\\\":\\\"2026-07-28T10:00:00.000Z\\\",\\\"supporterEarlyAccessEnabled\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/models/{modelId}/versions/{versionId}/training-metadata-raw": { "get": { "description": "Return the public raw safetensors metadata extracted for one visible model version. File paths, secrets, and other protected training values remain redacted by the runtime policy.", "operationId": "getModelVersionTrainingMetadata", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "metadata": {}, "source": "local", "versionId": 1 }, "schema": { "description": "Fields describing 200 response for api models model id versions version id training metadata raw in Developer API requests and responses.", "properties": { "metadata": { "description": "Structured metadata details for this 200 response for api models model id versions version id training metadata raw.", "nullable": true, "type": "object" }, "source": { "description": "Source associated with this 200 response for api models model id versions version id training metadata raw; preserve server-returned values when passing them to another operation. Supported values: `local`, `remote`.", "enum": [ "local", "remote" ], "nullable": true, "type": "string" }, "versionId": { "description": "Stable identifier for the version; use it in subsequent API calls instead of a display name.", "type": "integer" } }, "type": "object" } } }, "description": "Raw training metadata payload.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model/version id or relationship mismatch.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found or inaccessible.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve raw safetensors __metadata__ for a specific model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/training-metadata-raw' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/training-metadata-raw', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/training-metadata-raw',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/training-metadata.toml": { "get": { "description": "Download a redacted LoRA training configuration as TOML for one visible model version. Callers should preserve the returned filename and treat omitted sensitive values as intentional.", "operationId": "downloadModelVersionTrainingMetadataToml", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/toml": { "schema": { "description": "200 response for api models model Id versions version Id training metadata toml value documented for this operation.", "type": "string" } } }, "description": "Redacted TOML training configuration.", "headers": { "Content-Disposition": { "description": "Attachment disposition containing the generated TOML filename.", "schema": { "example": "attachment; filename=\"model-14474-version-16198-training.toml\"", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model/version id or relationship mismatch.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found, inaccessible, not a LoRA model, or no training metadata available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download a redacted LoRA training TOML for a specific model version", "tags": [ "Downloads" ], "x-api-key-required-scope": "ModelsRead", "x-api-key-required-scope-mask": 4, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/models/123/versions/123/training-metadata.toml' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/training-metadata.toml', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/models/123/versions/123/training-metadata.toml',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/models/{modelId}/versions/{versionId}/videos": { "patch": { "description": "Replace the sample-video order for a model version after validating the complete set of attached video identifiers. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "reorderModelVersionVideos", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "videoIds": [ 1 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "videoIds": { "description": "New order of video IDs.", "items": { "description": "Numeric video ids item reported for this video ids.", "type": "integer" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Videos reordered successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid video IDs or order.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Reorder videos for a specific model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/models/123/versions/123/videos' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"videoIds\":[1]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/videos', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"videoIds\": [\n 1\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/models/123/versions/123/videos',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"videoIds\\\":[1]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "post": { "description": "Upload validated sample videos and optional preview images to a caller-managed model version. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadModelVersionVideos", "parameters": [ { "description": "Model Id provided in the path.", "example": 1, "in": "path", "name": "modelId", "required": true, "schema": { "description": "Model Id value documented for this operation.", "type": "integer" } }, { "description": "Version Id provided in the path.", "example": 1, "in": "path", "name": "versionId", "required": true, "schema": { "description": "Version Id value documented for this operation.", "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "description": "example", "metaImages": [ "example" ], "tags": "example", "title": "example", "videoFiles": [ "example" ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "type": "string" }, "metaImages": { "description": "Optional preview images.", "items": { "description": "Meta Images item associated with this meta images; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "type": "array" }, "tags": { "description": "Comma-separated list of tags.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" }, "videoFiles": { "description": "Array of video files.", "items": { "description": "Video Files item associated with this video files; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "videoIds": [ 73, 74 ] }, "schema": { "$ref": "#/components/schemas/DeveloperVideoUploadResponse" } } }, "description": "Version video(s) uploaded successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "videoIds": [ 73, 74 ] }, "schema": { "$ref": "#/components/schemas/DeveloperVideoUploadResponse" } } }, "description": "Some videos were rejected while the remaining videos were stored.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request (e.g. no files uploaded).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Version not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "servers": [ { "description": "Use the dedicated upload host for file-transfer routes.", "url": "https://uploads.arcenciel.io" } ], "summary": "Upload one or more videos for a specific model version", "tags": [ "Models" ], "x-api-key-required-scope": "ModelsWrite", "x-api-key-required-scope-mask": 8, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/models/123/versions/123/videos' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/models/123/versions/123/videos', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/models/123/versions/123/videos',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/notifications": { "get": { "description": "List only the authenticated caller’s notifications with opaque cursor pagination, unread filtering, and the documented category taxonomy.", "operationId": "listNotifications", "parameters": [ { "description": "Max number of notifications to return (default 50).", "example": 1, "in": "query", "name": "limit", "schema": { "description": "Limit value documented for this operation. Minimum: 1. Maximum: 100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor for pagination.", "example": "next-page", "in": "query", "name": "cursor", "schema": { "description": "Cursor value documented for this operation.", "type": "string" } }, { "description": "When true, only unread notifications are returned.", "example": true, "in": "query", "name": "unreadOnly", "schema": { "description": "Unread Only value documented for this operation.", "type": "boolean" } }, { "description": "Server-side category filter. Works with cursor pagination.", "example": "all", "in": "query", "name": "category", "schema": { "description": "Category value documented for this operation.", "enum": [ "all", "unread", "following", "comments", "reactions", "updates", "collections", "collabs", "system", "moderation" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "comment": { "id": 912, "targetId": 52, "targetType": "MODEL" }, "commentId": 912, "createdAt": "2026-08-07T10:00:00.000Z", "id": 501, "isRead": false, "message": "A creator commented on your model.", "type": "NEW_COMMENT", "updatedAt": "2026-08-07T10:00:00.000Z", "userId": 42 } ], "hasMore": false, "limit": 50, "nextCursor": null }, "schema": { "$ref": "#/components/schemas/DeveloperNotificationPage" } } }, "description": "A paginated list of notification objects.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve your notifications", "tags": [ "Notifications" ], "x-api-key-required-scope": "NotificationsRead", "x-api-key-required-scope-mask": 262144, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/notifications' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/notifications', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/notifications',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "notifications", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/notifications/readAll": { "post": { "description": "Mark all matching notifications for the authenticated caller as read, optionally restricted to a documented notification category.", "operationId": "markAllNotificationsRead", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "category": "all", "unreadOnly": true }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "category": { "description": "Optional category scope. Defaults to `all`.", "enum": [ "all", "unread", "following", "comments", "reactions", "updates", "collections", "collabs", "system", "moderation" ], "type": "string" }, "unreadOnly": { "description": "Optional flag for clients that only want unread scope.", "type": "boolean" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": false }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "All notifications marked as read successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid category.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Mark notifications as read (optionally scoped by category)", "tags": [ "Notifications" ], "x-api-key-required-scope": "NotificationsWrite", "x-api-key-required-scope-mask": 524288, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/notifications/readAll' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"category\":\"all\",\"unreadOnly\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/notifications/readAll', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"category\": \"all\",\n \"unreadOnly\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/notifications/readAll',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"category\\\":\\\"all\\\",\\\"unreadOnly\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "notifications", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/notifications/readMany": { "post": { "description": "Mark a bounded set of notification identifiers owned by the authenticated caller as read. Identifiers belonging to other users are never changed.", "operationId": "markNotificationsRead", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "notificationIds": [ 1 ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "notificationIds": { "description": "IDs belonging to the current user.", "items": { "description": "Numeric notification ids item reported for this notification ids.", "type": "integer" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Notifications marked as read successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "No notification IDs provided.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Mark specific notifications as read", "tags": [ "Notifications" ], "x-api-key-required-scope": "NotificationsWrite", "x-api-key-required-scope-mask": 524288, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/notifications/readMany' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"notificationIds\":[1]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/notifications/readMany', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"notificationIds\": [\n 1\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/notifications/readMany',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"notificationIds\\\":[1]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "notifications", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/notifications/summary": { "get": { "description": "Return total and unread notification counts for the authenticated caller, grouped by current server types and user-facing categories.", "operationId": "getNotificationSummary", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "byCategory": { "comments": { "total": 4, "unread": 1 } }, "byType": { "NEW_COMMENT": { "total": 4, "unread": 1 } }, "total": 12, "unread": 3 }, "schema": { "$ref": "#/components/schemas/DeveloperNotificationSummary" } } }, "description": "Aggregate notification counts for the current user.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve notification totals and per-type counts", "tags": [ "Notifications" ], "x-api-key-required-scope": "NotificationsRead", "x-api-key-required-scope-mask": 262144, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/notifications/summary' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/notifications/summary', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/notifications/summary',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "notifications", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/notifications/{notificationId}/read": { "patch": { "description": "Mark one notification owned by the authenticated caller as read. Other users’ notification identifiers always remain inaccessible.", "operationId": "markNotificationRead", "parameters": [ { "description": "The ID of the notification to mark as read.", "example": 1, "in": "path", "name": "notificationId", "required": true, "schema": { "description": "Notification Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Notification marked as read successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Notification not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Mark a specific notification as read", "tags": [ "Notifications" ], "x-api-key-required-scope": "NotificationsWrite", "x-api-key-required-scope-mask": 524288, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/notifications/123/read' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/notifications/123/read', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/notifications/123/read',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "notifications", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/tags/usage": { "get": { "description": "List public tag usage statistics for discovery and suggestion interfaces. Authentication is optional and clients should tolerate new tag metadata fields and newly introduced records.", "operationId": "listTagUsage", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": [ { "count": 5, "id": 1, "name": "example" } ], "schema": { "description": "Ordered 200 response for api tags usage values returned by this operation.", "items": { "description": "Structured 200 response for api tags usage item details for this 200 response for api tags usage.", "properties": { "count": { "description": "Number of count records represented by this 200 response for api tags usage item.", "example": 5, "type": "integer" }, "id": { "description": "Stable identifier for the 200 response for api tags usage item; use it in subsequent API calls instead of a display name.", "example": 1, "type": "integer" }, "name": { "description": "Human-readable name for this 200 response for api tags usage item; it is not a stable identifier.", "example": "example", "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "Array of tags with usage counts", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve tag usage statistics", "tags": [ "Tags" ], "x-api-key-required-scope": "None", "x-api-key-scope-exempt": true, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/tags/usage' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/tags/usage', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/tags/usage',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/users": { "get": { "description": "List public user profiles with the documented pagination and filtering controls. Private account, security, email, and session data is never part of this Developer API response.", "operationId": "listUsers", "parameters": [ { "description": "Filter by username (contains match).", "example": "landscape", "in": "query", "name": "search", "schema": { "description": "Search value documented for this operation.", "type": "string" } }, { "description": "Filter by user role.", "example": "ADMIN", "in": "query", "name": "role", "schema": { "description": "Role value documented for this operation. Supported values: `ADMIN`, `MODERATOR`, `CREATOR`, `ARTIST`, `USER`.", "enum": [ "ADMIN", "MODERATOR", "CREATOR", "ARTIST", "USER" ], "type": "string" } }, { "description": "When true, return users followed by the current user (auth only).", "example": true, "in": "query", "name": "followed", "schema": { "description": "Followed value documented for this operation.", "type": "boolean" } }, { "description": "Sort field (default username).", "example": "username", "in": "query", "name": "sort", "schema": { "description": "Sort value documented for this operation. Supported values: `username`, `role`, `createdAt`, `imageCount`, `modelCount`, `articleCount`, `videoCount`.", "enum": [ "username", "role", "createdAt", "imageCount", "modelCount", "articleCount", "videoCount" ], "type": "string" } }, { "description": "Sort direction (default desc).", "example": "asc", "in": "query", "name": "direction", "schema": { "description": "Direction value documented for this operation. Supported values: `asc`, `desc`.", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Page number.", "example": 1, "in": "query", "name": "page", "schema": { "default": 1, "description": "Page value documented for this operation.", "type": "integer" } }, { "description": "Page size (min 10, max 100).", "example": 40, "in": "query", "name": "limit", "schema": { "default": 40, "description": "Limit value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "email": "user@example.com", "id": 2, "profilePicture": "profile/john_doe.png", "role": "USER", "username": "exampleUser" } ], "hasMore": true, "limit": 1, "page": 1, "total": 1 }, "schema": { "description": "Fields describing 200 response for api users in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api users; an empty list means none are available.", "items": { "$ref": "#/components/schemas/User" }, "type": "array" }, "hasMore": { "description": "Whether another page of this 200 response for api users is available after the current result.", "type": "boolean" }, "limit": { "description": "Maximum number of records requested or returned in one page of this 200 response for api users.", "type": "integer" }, "page": { "description": "One-based result page requested or returned for this 200 response for api users.", "type": "integer" }, "total": { "description": "Total number of matching records across all pages for this 200 response for api users.", "type": "integer" } }, "type": "object" } } }, "description": "Returns a paginated list of users.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve a list of users.", "tags": [ "Users" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/users/me": { "get": { "description": "Return the authenticated caller’s own profile and account preferences without exposing write-only credentials or raw authentication secrets.", "operationId": "getMyProfile", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "articleCount": 1, "bio": "Hello, I'm John.", "createdAt": "2025-02-26T10:00:00Z", "followersCount": 5, "id": 1, "imageCount": 20, "isFollowed": false, "modelCount": 10, "profileBanner": "banners/john_banner.jpg", "profilePicture": "profile/john_doe.png", "role": "USER", "socialLinks": [], "username": "john_doe", "videoCount": 3 }, "schema": { "$ref": "#/components/schemas/UserProfile" } } }, "description": "Returns the profile of the current user.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized – user not logged in.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve the current user's profile", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/me' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/me',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update supported fields on the authenticated caller’s profile. Username conflicts, validation failures, and preference constraints are returned explicitly.", "operationId": "updateMyProfile", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "bio": "value", "nsfwAgeVerified": true, "sfwMode": true, "trackDownloads": true, "username": "value" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "bio": { "description": "Bio associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "nsfwAgeVerified": { "description": "Whether nsfw age verified applies to this request payload.", "type": "boolean" }, "sfwMode": { "description": "Whether sfw mode applies to this request payload.", "type": "boolean" }, "trackDownloads": { "description": "Whether track downloads applies to this request payload.", "type": "boolean" }, "username": { "description": "Username associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" } } }, "description": "Fields to update in your profile.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "apiKeys": [], "articleCount": 1, "bio": "Hello, I'm John.", "civitaiApiKey": null, "createdAt": "2025-02-26T10:00:00Z", "dateFormat": "yyyy-MM-dd HH:mm", "discordLinked": true, "email": "john@example.com", "followersCount": 5, "hasCivitaiApiKey": true, "id": 1, "imageCount": 20, "isFollowed": false, "modelCount": 10, "profileBanner": "banners/john_banner.jpg", "profilePicture": "profile/john_doe.png", "role": "USER", "sfwMode": false, "socialLinks": [], "trackDownloads": true, "uploads": { "articles": [], "images": [], "models": [], "videos": [] }, "username": "john_doe", "videoCount": 3 }, "schema": { "$ref": "#/components/schemas/SelfProfile" } } }, "description": "Profile updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request – invalid data.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update your own profile fields (e.g. username, bio, sfwMode, trackDownloads)", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/users/me' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"username\":\"value\",\"bio\":\"value\",\"sfwMode\":true,\"nsfwAgeVerified\":true,\"trackDownloads\":true}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"username\": \"value\",\n \"bio\": \"value\",\n \"sfwMode\": true,\n \"nsfwAgeVerified\": true,\n \"trackDownloads\": true\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/users/me',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"username\\\":\\\"value\\\",\\\"bio\\\":\\\"value\\\",\\\"sfwMode\\\":true,\\\"nsfwAgeVerified\\\":true,\\\"trackDownloads\\\":true}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/users/me/banner": { "delete": { "description": "Remove the authenticated caller’s current profile banner and managed derivative files. The operation cannot affect another user’s media.", "operationId": "removeMyProfileBanner", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "message": "Profile banner removed successfully" }, "schema": { "description": "Fields describing 200 response for api users me banner in Developer API requests and responses.", "properties": { "message": { "description": "Message associated with this 200 response for api users me banner; preserve server-returned values when passing them to another operation.", "example": "Profile banner removed successfully", "type": "string" } }, "type": "object" } } }, "description": "Profile banner removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove your profile banner.", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/users/me/banner' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/banner', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/users/me/banner',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Upload and replace the authenticated caller’s profile banner using validated multipart image content. Clients must not retry uploads automatically.", "operationId": "updateMyProfileBanner", "parameters": [], "requestBody": { "content": { "multipart/form-data": { "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "bannerFile": { "description": "Banner File associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" } }, "type": "object" } } }, "description": "Multipart form-data containing the banner file.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Profile banner updated successfully", "profileBanner": "value" }, "schema": { "description": "Fields describing 200 response for api users me banner in Developer API requests and responses.", "properties": { "message": { "description": "Message associated with this 200 response for api users me banner; preserve server-returned values when passing them to another operation.", "example": "Profile banner updated successfully", "type": "string" }, "profileBanner": { "description": "Profile Banner associated with this 200 response for api users me banner; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" } } }, "description": "Profile banner updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload or change your profile banner.", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/users/me/banner' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/banner', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/users/me/banner',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/users/me/downloads": { "delete": { "description": "Clear all tracked download-history entries for the authenticated caller. This does not remove models, versions, files, or global aggregate statistics.", "operationId": "clearMyDownloads", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Downloads cleared.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove all downloads", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/users/me/downloads' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/downloads', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/users/me/downloads',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "List the authenticated caller’s tracked model download history with model and version context. This operation never returns another user’s records.", "operationId": "listMyDownloads", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": [], "schema": { "items": { "$ref": "#/components/schemas/DeveloperDownloadHistoryEntry" }, "type": "array" } } }, "description": "Array of downloads.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List your recent downloads", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/me/downloads' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/downloads', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/me/downloads',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/users/me/downloads/{id}": { "delete": { "description": "Delete one tracked download-history entry owned by the authenticated caller. The underlying model file and aggregate download counts are unaffected.", "operationId": "deleteMyDownload", "parameters": [ { "description": "Id provided in the path.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Download removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Download not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove a specific download entry", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/users/me/downloads/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/downloads/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/users/me/downloads/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/users/me/export": { "get": { "description": "Export the authenticated caller’s account data, uploads, comments, and audit records. The privacy-sensitive export is limited to one request per 24 hours.", "operationId": "exportMyData", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "audit": [], "comments": [], "profile": {}, "uploads": { "articles": [], "images": [], "models": [], "videos": [] } }, "schema": { "$ref": "#/components/schemas/DeveloperDataExport" } } }, "description": "Returns profile, uploads, comments and audit logs.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too many requests.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Export all your account data", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/me/export' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/export', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/me/export',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1, "policyId": "user-data-export", "scope": "user, trusted API key, or client IP", "windowSeconds": 86400 }, "x-sdk-retry-classification": "safe" } }, "/api/users/me/pinned-template": { "get": { "description": "List the model identifiers pinned by the authenticated caller as quick upload templates. At most the current configured limit is returned.", "operationId": "listPinnedTemplates", "parameters": [ { "description": "Include compact model records in addition to identifiers.", "example": false, "in": "query", "name": "compact", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Maximum versions included per compact model.", "example": 20, "in": "query", "name": "versionLimit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "modelIds": [ 12, 18 ] }, "schema": { "$ref": "#/components/schemas/DeveloperPinnedTemplatesResponse" } } }, "description": "Returns the list of pinned models.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve the model ids pinned as quick upload templates", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/me/pinned-template' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/pinned-template', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/me/pinned-template',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Toggle a model in the authenticated caller’s quick-upload template list. Automatic retries are disabled because the endpoint toggles state.", "operationId": "togglePinnedTemplate", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "modelId": 1 }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "modelId": { "description": "Stable identifier for the model; use it in subsequent API calls instead of a display name.", "type": "integer" } }, "required": [ "modelId" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Pinned templates updated", "modelIds": [ 12, 18 ] }, "schema": { "$ref": "#/components/schemas/DeveloperPinnedTemplatesResponse" } } }, "description": "Pinned templates updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid model id or limit reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Model not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Toggle a model as pinned upload template", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/users/me/pinned-template' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"modelId\":1}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/pinned-template', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"modelId\": 1\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/users/me/pinned-template',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"modelId\\\":1}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "profile-pinned-template", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/users/me/profile-picture": { "delete": { "description": "Remove the authenticated caller’s current profile picture and its managed derivative files. Repeating the request leaves the profile without an image.", "operationId": "removeMyProfilePicture", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "message": "Profile picture removed successfully" }, "schema": { "description": "Fields describing 200 response for api users me profile picture in Developer API requests and responses.", "properties": { "message": { "description": "Message associated with this 200 response for api users me profile picture; preserve server-returned values when passing them to another operation.", "example": "Profile picture removed successfully", "type": "string" } }, "type": "object" } } }, "description": "Profile picture removed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove your profile picture.", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/users/me/profile-picture' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/profile-picture', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/users/me/profile-picture',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Upload and replace the authenticated caller’s profile picture using validated multipart image content. Clients must not retry uploads automatically.", "operationId": "updateMyProfilePicture", "parameters": [], "requestBody": { "content": { "multipart/form-data": { "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "profilePictureFile": { "description": "Profile Picture File associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" } }, "type": "object" } } }, "description": "Multipart form-data containing the profile picture file.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Profile picture updated successfully", "profilePicture": "value" }, "schema": { "description": "Fields describing 200 response for api users me profile picture in Developer API requests and responses.", "properties": { "message": { "description": "Message associated with this 200 response for api users me profile picture; preserve server-returned values when passing them to another operation.", "example": "Profile picture updated successfully", "type": "string" }, "profilePicture": { "description": "Profile Picture associated with this 200 response for api users me profile picture; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" } } }, "description": "Profile picture updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload or change your profile picture.", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/users/me/profile-picture' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/profile-picture', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/users/me/profile-picture',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/users/me/social-links": { "patch": { "description": "Replace the authenticated caller’s supported public social links after URL normalization and platform validation. Unknown platforms are rejected.", "operationId": "updateMySocialLinks", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "links": [ { "icon": "ri-github-fill", "url": "https://github.com/arcenciel" } ] }, "schema": { "properties": { "links": { "items": { "properties": { "icon": { "example": "ri-github-fill", "type": "string" }, "url": { "example": "https://github.com/arcenciel", "format": "uri", "maxLength": 2048, "type": "string" } }, "required": [ "url" ], "type": "object" }, "maxItems": 10, "type": "array" } }, "required": [ "links" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Social links updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update your social links", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/users/me/social-links' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"links\":[{\"icon\":\"ri-github-fill\",\"url\":\"https://github.com/arcenciel\"}]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/social-links', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"links\": [\n {\n \"icon\": \"ri-github-fill\",\n \"url\": \"https://github.com/arcenciel\"\n }\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/users/me/social-links',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"links\\\":[{\\\"icon\\\":\\\"ri-github-fill\\\",\\\"url\\\":\\\"https://github.com/arcenciel\\\"}]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/users/me/uploads": { "get": { "description": "Return models, images, videos, and articles owned by the authenticated caller, including non-public items available through owner visibility.", "operationId": "listMyUploads", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "articles": [ { "createdAt": "2025-02-26T10:00:00Z", "expiresAt": null, "id": 42, "lastUsedAt": null, "name": "Automation key", "preview": "9fa3b7", "revokedAt": null, "scopeMask": 33554431, "usageCount": 0 } ], "images": [ { "createdAt": "2025-02-26T10:00:00Z", "expiresAt": null, "id": 42, "lastUsedAt": null, "name": "Automation key", "preview": "9fa3b7", "revokedAt": null, "scopeMask": 33554431, "usageCount": 0 } ], "models": [ { "email": "user@example.com", "id": 2, "profilePicture": "profile/john_doe.png", "role": "USER", "username": "exampleUser" } ], "videos": [ { "createdAt": "2025-02-26T10:00:00Z", "expiresAt": null, "id": 42, "lastUsedAt": null, "name": "Automation key", "preview": "9fa3b7", "revokedAt": null, "scopeMask": 33554431, "usageCount": 0 } ] }, "schema": { "$ref": "#/components/schemas/Uploads" } } }, "description": "Returns an object containing arrays of your uploads.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve your uploaded content (models, images, videos, articles)", "tags": [ "Profile" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/me/uploads' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/me/uploads', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/me/uploads',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/users/resolve": { "post": { "description": "Resolve a bounded list of public usernames to numeric user identifiers. Authentication is optional and API keys need only ProfileRead for this read-like POST.", "operationId": "resolveUsers", "parameters": [], "requestBody": { "content": { "application/json": { "example": { "names": [ "value" ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "names": { "description": "Array of usernames to resolve.", "items": { "description": "Names item associated with this names; preserve server-returned values when passing them to another operation.", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": {}, "schema": { "additionalProperties": { "nullable": true, "type": "integer" }, "description": "Fields describing 200 response for api users resolve in Developer API requests and responses.", "type": "object" } } }, "description": "Mapping from username to user ID (null if not found).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Resolve usernames to user IDs", "tags": [ "Users" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/users/resolve' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"names\":[\"value\"]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/resolve', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"names\": [\n \"value\"\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/users/resolve',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"names\\\":[\\\"value\\\"]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/users/search": { "get": { "description": "Search public user profiles by username for attribution and creator-picking workflows. Results contain only public profile fields and clients must not infer account availability.", "operationId": "searchUsers", "parameters": [ { "description": "Partial username to search for (min 2 characters).", "example": "landscape", "in": "query", "name": "q", "schema": { "description": "Q value documented for this operation.", "type": "string" } }, { "description": "Max number of users to return (default 10).", "example": 1, "in": "query", "name": "limit", "schema": { "description": "Limit value documented for this operation. Minimum: 1. Maximum: 25.", "maximum": 25, "minimum": 1, "type": "integer" } }, { "description": "Include collection collaborators in results.", "example": true, "in": "query", "name": "includeCollaborators", "schema": { "description": "Include Collaborators value documented for this operation.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "badges": [ { "icon": "value", "id": 1, "name": "value", "type": "value" } ], "id": 1, "profilePicture": "value", "profilePictureRating": "value", "relationLabel": "Owner", "username": "value" } ], "schema": { "description": "Ordered 200 response for api users search values returned by this operation.", "items": { "description": "Structured 200 response for api users search item details for this 200 response for api users search.", "properties": { "badges": { "description": "Ordered badges entries included with this 200 response for api users search item; an empty list means none are available.", "items": { "description": "Structured badges item details for this badges.", "properties": { "icon": { "description": "Icon associated with this badges item; preserve server-returned values when passing them to another operation.", "type": "string" }, "id": { "description": "Stable identifier for the badges item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "name": { "description": "Human-readable name for this badges item; it is not a stable identifier.", "type": "string" }, "type": { "description": "Discriminator identifying the kind of badges item; clients should tolerate future values.", "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "Stable identifier for the 200 response for api users search item; use it in subsequent API calls instead of a display name.", "type": "integer" }, "profilePicture": { "description": "Profile Picture associated with this 200 response for api users search item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "profilePictureRating": { "description": "Profile Picture Rating associated with this 200 response for api users search item; preserve server-returned values when passing them to another operation.", "nullable": true, "type": "string" }, "relationLabel": { "description": "Relation Label associated with this 200 response for api users search item; preserve server-returned values when passing them to another operation. Supported values: `Owner`, `Collaborator`.", "enum": [ "Owner", "Collaborator" ], "type": "string" }, "username": { "description": "Username associated with this 200 response for api users search item; preserve server-returned values when passing them to another operation.", "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "A list of matching users.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search for users by username", "tags": [ "Users" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/search' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/search', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/search',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/users/{id}": { "get": { "description": "Return the public profile for one visible user, including only fields approved for external integrations. Account-security and private contact data remains outside this contract.", "operationId": "getUser", "parameters": [ { "description": "The user ID.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "articleCount": 1, "bio": "Hello, I'm John.", "createdAt": "2025-02-26T10:00:00Z", "followersCount": 5, "id": 1, "imageCount": 20, "isFollowed": false, "modelCount": 10, "profileBanner": "banners/john_banner.jpg", "profilePicture": "profile/john_doe.png", "role": "USER", "socialLinks": [], "username": "john_doe", "videoCount": 3 }, "schema": { "$ref": "#/components/schemas/UserProfile" } } }, "description": "Returns the user's profile.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "User not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve a specific user's profile.", "tags": [ "Users" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/users/{id}/follow": { "delete": { "description": "Remove the authenticated caller’s follow relationship with a user. Repeating the operation cannot recreate the relationship.", "operationId": "unfollowUser", "parameters": [ { "description": "The ID of the user to unfollow.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Unfollow successful.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Unfollow a user.", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/users/123/follow' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/123/follow', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/users/123/follow',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "post": { "description": "Follow a visible user as the authenticated caller. The runtime prevents self-following and duplicate relationships and emits the normal notification workflow.", "operationId": "followUser", "parameters": [ { "description": "The ID of the user to follow.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Follow successful.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Follow a user.", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/users/123/follow' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/123/follow', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/users/123/follow',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "social-follow", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/users/{id}/profile-picture/report": { "post": { "description": "Report a user avatar for moderation. Reuse an Idempotency-Key for safe retries; a duplicate caller report returns 204 without a response body.", "operationId": "reportUserAvatar", "parameters": [ { "description": "Id provided in the path.", "example": 108, "in": "path", "name": "id", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Content reported successfully" }, "schema": { "$ref": "#/components/schemas/DeveloperReportResponse" } } }, "description": "Avatar reported successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "204": { "description": "Avatar already reported by this user.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid user id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Report a user's avatar for moderation", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "ProfileWrite", "x-api-key-required-scope-mask": 2, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/users/123/profile-picture/report' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/123/profile-picture/report', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/users/123/profile-picture/report',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "report-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/users/{id}/uploads": { "get": { "description": "List models, images, videos, articles, and other upload groups visible on one public user profile. Every nested record is filtered using its domain visibility policy.", "operationId": "listUserUploads", "parameters": [ { "description": "The user ID.", "example": 1, "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "integer" } }, { "description": "Sort order for results.", "example": "recent", "in": "query", "name": "sort", "schema": { "description": "Sort value documented for this operation. Supported values: `recent`, `oldest`.", "enum": [ "recent", "oldest" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "articles": [ { "createdAt": "2025-02-26T10:00:00Z", "expiresAt": null, "id": 42, "lastUsedAt": null, "name": "Automation key", "preview": "9fa3b7", "revokedAt": null, "scopeMask": 33554431, "usageCount": 0 } ], "images": [ { "createdAt": "2025-02-26T10:00:00Z", "expiresAt": null, "id": 42, "lastUsedAt": null, "name": "Automation key", "preview": "9fa3b7", "revokedAt": null, "scopeMask": 33554431, "usageCount": 0 } ], "models": [ { "email": "user@example.com", "id": 2, "profilePicture": "profile/john_doe.png", "role": "USER", "username": "exampleUser" } ], "videos": [ { "createdAt": "2025-02-26T10:00:00Z", "expiresAt": null, "id": 42, "lastUsedAt": null, "name": "Automation key", "preview": "9fa3b7", "revokedAt": null, "scopeMask": 33554431, "usageCount": 0 } ] }, "schema": { "$ref": "#/components/schemas/Uploads" } } }, "description": "Lists of uploads grouped by type.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve uploads for a specific user", "tags": [ "Users" ], "x-api-key-required-scope": "ProfileRead", "x-api-key-required-scope-mask": 1, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/users/123/uploads' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/users/123/uploads', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/users/123/uploads',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/search": { "get": { "description": "Search visible videos with pagination, rating, tag, model, and ownership filters. Returned media is limited by publication, ownership, and adult-content policy for the caller.", "operationId": "searchVideos", "parameters": [ { "description": "Search query applied to title, description, and tags (comma-separated terms supported).", "example": "landscape", "in": "query", "name": "search", "schema": { "description": "Search value documented for this operation.", "type": "string" } }, { "description": "Sorting order for the videos (hot = recent videos sorted by reactions).", "example": "newest", "in": "query", "name": "sort", "schema": { "description": "Sort value documented for this operation. Supported values: `newest`, `oldest`, `reactions`, `random`, `hot`.", "enum": [ "newest", "oldest", "reactions", "random", "hot" ], "type": "string" } }, { "description": "Page number for pagination.", "example": 1, "in": "query", "name": "page", "schema": { "default": 1, "description": "Page value documented for this operation.", "type": "integer" } }, { "description": "Number of items per page (max 1000).", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "description": "Limit value documented for this operation.", "type": "integer" } }, { "description": "Comma-separated list of ratings to include (safe, questionable, sensitive, explicit).", "example": "example-ratings", "in": "query", "name": "ratings", "schema": { "description": "Ratings value documented for this operation.", "type": "string" } }, { "description": "Filter videos by uploader id.", "example": 1, "in": "query", "name": "userId", "schema": { "description": "User Id value documented for this operation.", "type": "integer" } }, { "description": "Auth only. Filter videos reacted to by the current user (optionally specify a reaction type).", "example": "example-self-reacted", "in": "query", "name": "selfReacted", "schema": { "description": "Self Reacted value documented for this operation.", "type": "string" } }, { "description": "Auth only. Return videos uploaded by users the current user follows.", "example": true, "in": "query", "name": "selfFollowing", "schema": { "description": "Self Following value documented for this operation.", "type": "boolean" } }, { "description": "Cursor for keyset pagination (use nextCursor from a previous response; only supported for newest/oldest).", "example": "next-page", "in": "query", "name": "cursor", "schema": { "description": "Cursor value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "createdAt": "2025-01-01T12:00:00Z", "description": "A sample video description.", "dislike": 2, "filePath": "videos/sample.mp4", "heart": 5, "id": "abc123", "like": 10, "streamManifestPath": "videos/sample_hls/index.m3u8", "tags": [ "demo", "sample" ], "title": "Sample Video", "updatedAt": "2025-01-02T09:00:00Z", "uploader": { "id": 1, "username": "john_doe" } } ], "hasMore": true, "limit": 1, "nextCursor": "value", "page": 1, "showcased": [ { "createdAt": "2025-01-01T12:00:00Z", "description": "A sample video description.", "dislike": 2, "filePath": "videos/sample.mp4", "heart": 5, "id": "abc123", "like": 10, "streamManifestPath": "videos/sample_hls/index.m3u8", "tags": [ "demo", "sample" ], "title": "Sample Video", "updatedAt": "2025-01-02T09:00:00Z", "uploader": { "id": 1, "username": "john_doe" } } ], "totalCount": 1, "totalPages": 1 }, "schema": { "description": "Fields describing 200 response for api videos search in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api videos search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Video" }, "type": "array" }, "hasMore": { "description": "Whether another page of this 200 response for api videos search is available after the current result.", "type": "boolean" }, "limit": { "description": "Maximum number of records requested or returned in one page of this 200 response for api videos search.", "type": "integer" }, "nextCursor": { "description": "Opaque continuation token for the next page of this 200 response for api videos search; absent or null means iteration is complete.", "nullable": true, "type": "string" }, "page": { "description": "One-based result page requested or returned for this 200 response for api videos search.", "type": "integer" }, "showcased": { "description": "Ordered showcased entries included with this 200 response for api videos search; an empty list means none are available.", "items": { "$ref": "#/components/schemas/Video" }, "type": "array" }, "totalCount": { "description": "Total number of matching records across all pages for this 200 response for api videos search.", "type": "integer" }, "totalPages": { "description": "Total number of pages available at the current page size for this 200 response for api videos search.", "type": "integer" } }, "type": "object" } } }, "description": "A paginated list of videos.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Search videos", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/search' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/search', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/search',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "content-search", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/upload": { "post": { "description": "Upload up to twenty validated videos with optional preview images and preserve accepted identifiers on partial failure. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "uploadVideos", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "example": { "description": "example", "duration": 1, "format": "example", "fps": 1, "tags": "example", "title": "example", "videoFile": "example" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "type": "string" }, "duration": { "description": "Duration of the video in seconds.", "type": "number" }, "format": { "description": "File format (e.g. mp4, webm).", "type": "string" }, "fps": { "description": "Frames per second.", "type": "number" }, "tags": { "description": "Tags associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" }, "videoFile": { "description": "Video File associated with this request payload; preserve server-returned values when passing them to another operation. Format: binary.", "format": "binary", "type": "string" } }, "type": "object" } } }, "description": "Multipart form-data payload containing the video file and metadata.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "videoIds": [ 73, 74 ] }, "schema": { "$ref": "#/components/schemas/DeveloperVideoUploadResponse" } } }, "description": "Video uploaded successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "202": { "content": { "application/json": { "example": { "videoIds": [ 73, 74 ] }, "schema": { "$ref": "#/components/schemas/DeveloperVideoUploadResponse" } } }, "description": "Some videos were rejected while the remaining videos were stored.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Bad request (e.g. no file provided or invalid file format).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Upload a video", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosWrite", "x-api-key-required-scope-mask": 512, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/videos/upload' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/upload', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/videos/upload',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/videos/{id}": { "delete": { "description": "Delete a caller-managed video, its poster and stream derivatives, and dependent associations after authorization checks. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "deleteVideo", "parameters": [ { "description": "The ID of the video to delete.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Video deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden – not the owner or admin/mod.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a video (only author or admin/mod)", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosDelete", "x-api-key-required-scope-mask": 1024, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/videos/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/videos/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Return metadata for one visible video, including the public uploader, tags, linked resources, reactions, and available stream metadata appropriate for the caller.", "operationId": "getVideo", "parameters": [ { "description": "The ID of the video.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdAt": "2025-01-01T12:00:00Z", "description": "A sample video description.", "dislike": 2, "filePath": "videos/sample.mp4", "heart": 5, "id": "abc123", "like": 10, "streamManifestPath": "videos/sample_hls/index.m3u8", "tags": [ "demo", "sample" ], "title": "Sample Video", "updatedAt": "2025-01-02T09:00:00Z", "uploader": { "id": 1, "username": "john_doe" } }, "schema": { "$ref": "#/components/schemas/Video" } } }, "description": "The video object.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve a video by its ID", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update supported metadata, prompt, generation parameters, tags, rating, and publication fields on a caller-managed video. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "updateVideo", "parameters": [ { "description": "ID of the video to edit.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "cfg": 1, "description": "value", "negativePrompt": "value", "prompt": "value", "rating": "value", "sampler": "value", "seed": "value", "steps": 1, "tags": "value", "title": "value" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "cfg": { "description": "Numeric cfg reported for this request payload.", "type": "number" }, "description": { "description": "User-facing description of this request payload; it may contain an empty string when no description was supplied.", "type": "string" }, "negativePrompt": { "description": "Negative Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "prompt": { "description": "Prompt text associated with generation of this request payload; availability depends on visibility and privacy rules.", "type": "string" }, "rating": { "description": "safe, questionable, sensitive or explicit", "type": "string" }, "sampler": { "description": "Sampler associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "seed": { "description": "Seed associated with this request payload; preserve server-returned values when passing them to another operation.", "type": "string" }, "steps": { "description": "Numeric steps reported for this request payload.", "type": "number" }, "tags": { "description": "Comma-separated list of tags.", "type": "string" }, "title": { "description": "Display title shown to users for this request payload.", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Video updated", "video": { "createdAt": "2025-01-01T12:00:00Z", "description": "A sample video description.", "dislike": 2, "filePath": "videos/sample.mp4", "heart": 5, "id": "abc123", "like": 10, "streamManifestPath": "videos/sample_hls/index.m3u8", "tags": [ "demo", "sample" ], "title": "Sample Video", "updatedAt": "2025-01-02T09:00:00Z", "uploader": { "id": 1, "username": "john_doe" } } }, "schema": { "$ref": "#/components/schemas/DeveloperVideoMutationResponse" } } }, "description": "Video updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid input.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Edit an existing video", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosWrite", "x-api-key-required-scope-mask": 512, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "roles": [ "ADMIN", "ARTIST", "CREATOR", "MODERATOR" ], "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/videos/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"title\":\"value\",\"description\":\"value\",\"prompt\":\"value\",\"negativePrompt\":\"value\",\"sampler\":\"value\",\"seed\":\"value\",\"cfg\":1,\"steps\":1,\"tags\":\"value\",\"rating\":\"value\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"title\": \"value\",\n \"description\": \"value\",\n \"prompt\": \"value\",\n \"negativePrompt\": \"value\",\n \"sampler\": \"value\",\n \"seed\": \"value\",\n \"cfg\": 1,\n \"steps\": 1,\n \"tags\": \"value\",\n \"rating\": \"value\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/videos/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"title\\\":\\\"value\\\",\\\"description\\\":\\\"value\\\",\\\"prompt\\\":\\\"value\\\",\\\"negativePrompt\\\":\\\"value\\\",\\\"sampler\\\":\\\"value\\\",\\\"seed\\\":\\\"value\\\",\\\"cfg\\\":1,\\\"steps\\\":1,\\\"tags\\\":\\\"value\\\",\\\"rating\\\":\\\"value\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/videos/{id}/download": { "get": { "description": "Download the original bytes of a visible video with a server-provided filename. The download limiter applies and clients should stream the response instead of buffering large files.", "operationId": "downloadVideo", "parameters": [ { "description": "The ID of the video to download.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "200 response for api videos id download value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "The video file as a binary stream.", "headers": { "Content-Disposition": { "description": "Attachment disposition containing the sanitized stored filename.", "schema": { "example": "attachment; filename=\"video-42.mp4\"", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found or file missing.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Download a video file", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123/download' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/download', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123/download',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 60, "policyId": "model-download", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 120, "windowSeconds": 300 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/{id}/hls/{quality}/{asset}": { "get": { "description": "Transfer an HLS variant playlist or transport-stream segment for a visible video. Callers must preserve the quality and asset path emitted by the master playlist.", "operationId": "getVideoHlsAsset", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } }, { "description": "HLS quality directory, such as 720p.", "example": "example-quality", "in": "path", "name": "quality", "required": true, "schema": { "description": "Quality value documented for this operation.", "type": "string" } }, { "description": "Playlist or transport-stream segment filename.", "example": "example-asset", "in": "path", "name": "asset", "required": true, "schema": { "description": "Asset value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.apple.mpegurl": { "schema": { "description": "200 response for api videos id hls quality asset value documented for this operation.", "type": "string" } }, "video/mp2t": { "schema": { "description": "200 response for api videos id hls quality asset value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Rewritten HLS playlist or MPEG transport stream segment.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video stream asset not found, or access denied.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve an authenticated HLS playlist or segment", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123/hls/value/value' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/hls/value/value', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123/hls/value/value',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/{id}/poster": { "get": { "description": "Transfer the poster image for a visible video after applying its rating and publication policy. Clients must honor the returned image Content-Type and cache headers.", "operationId": "getVideoPoster", "parameters": [ { "description": "The ID of the video poster to retrieve.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "description": "200 response for api videos id poster value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/png": { "schema": { "description": "200 response for api videos id poster value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "image/webp": { "schema": { "description": "200 response for api videos id poster value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Poster image.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video or poster not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve an authenticated video poster image", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123/poster' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/poster', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123/poster',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/{id}/publish": { "post": { "description": "Publish a caller-managed video immediately and apply the normal visibility, notification, and audit workflow. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "publishVideo", "parameters": [ { "description": "ID of the video to publish.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Video published.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Not allowed to publish this video.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Publish a video immediately", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosWrite", "x-api-key-required-scope-mask": 512, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/videos/123/publish' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/publish', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/videos/123/publish',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/videos/{id}/reactions": { "delete": { "description": "Remove the current caller’s reaction from a visible video. The response includes the updated video representation for UI reconciliation.", "operationId": "removeVideoReaction", "parameters": [ { "description": "The ID of the video.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Reaction removed" }, "schema": { "$ref": "#/components/schemas/DeveloperVideoReactionResponse" } } }, "description": "Reaction removed successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Remove your reaction from a video", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/videos/123/reactions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/reactions', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/videos/123/reactions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "post": { "description": "Set or replace the current caller’s reaction on a visible video. The returned video representation includes the reaction counts after the mutation.", "operationId": "setVideoReaction", "parameters": [ { "description": "The ID of the video.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "reactionType": "heart" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "reactionType": { "description": "The type of reaction.", "enum": [ "heart", "like", "dislike" ], "type": "string" } }, "type": "object" } } }, "description": "Reaction details.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Reaction updated", "videoId": 73 }, "schema": { "$ref": "#/components/schemas/DeveloperVideoReactionResponse" } } }, "description": "Reaction updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "React to a video", "tags": [ "Social" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/videos/123/reactions' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"reactionType\":\"heart\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/reactions', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"reactionType\": \"heart\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/videos/123/reactions',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"reactionType\\\":\\\"heart\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 30, "policyId": "social-reaction", "scope": "user, trusted API key, or client IP", "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/videos/{id}/related": { "get": { "description": "List videos related to one visible source video while filtering every result for publication, ownership, rating, and adult-content access of the current caller.", "operationId": "listRelatedVideos", "parameters": [ { "description": "The ID of the reference video.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "createdAt": "2025-01-01T12:00:00Z", "description": "A sample video description.", "dislike": 2, "filePath": "videos/sample.mp4", "heart": 5, "id": "abc123", "like": 10, "streamManifestPath": "videos/sample_hls/index.m3u8", "tags": [ "demo", "sample" ], "title": "Sample Video", "updatedAt": "2025-01-02T09:00:00Z", "uploader": { "id": 1, "username": "john_doe" } } ], "schema": { "description": "Ordered 200 response for api videos id related values returned by this operation.", "items": { "$ref": "#/components/schemas/Video" }, "type": "array" } } }, "description": "Related videos returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List videos related to a given video", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123/related' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/related', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123/related',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/{id}/report": { "post": { "description": "Report one video for moderation. Reuse an Idempotency-Key for safe retries; an existing caller report returns 204 and resolved targets reject new reports.", "operationId": "reportVideo", "parameters": [ { "description": "ID of the video to report.", "example": 108, "in": "path", "name": "id", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Content reported successfully" }, "schema": { "$ref": "#/components/schemas/DeveloperReportResponse" } } }, "description": "Video reported successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "204": { "description": "You have already reported this video.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Video already moderated and cannot be reported. The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Report a video", "tags": [ "Trust & Safety" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/videos/123/report' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/report', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/videos/123/report',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "report-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/videos/{id}/schedule": { "post": { "description": "Schedule a caller-managed video for a future publication time supplied as an ISO-8601 timestamp. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "scheduleVideo", "parameters": [ { "description": "ID of the video to schedule.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "publishAt": "2026-07-28T10:00:00.000Z" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "publishAt": { "description": "Timestamp when the video should be published.", "format": "date-time", "type": "string" } }, "required": [ "publishAt" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Video scheduled.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid publish date.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Not allowed to schedule this video.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Schedule publishing of a video", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosWrite", "x-api-key-required-scope-mask": 512, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/videos/123/schedule' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"publishAt\":\"2026-07-28T10:00:00.000Z\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/schedule', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"publishAt\": \"2026-07-28T10:00:00.000Z\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/videos/123/schedule',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"publishAt\\\":\\\"2026-07-28T10:00:00.000Z\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 180, "policyId": "standard-post", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 360, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/videos/{id}/showcased": { "patch": { "description": "Set the explicit showcased state for a caller-owned video while enforcing the per-profile showcase limit. The documented owner/staff checks, API-key scope, rate policy, and retry classification apply to every call.", "operationId": "setVideoShowcase", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Comment deleted" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Showcase state updated.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Showcase or unshowcase a video", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosWrite", "x-api-key-required-scope-mask": 512, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/videos/123/showcased' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/showcased', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/videos/123/showcased',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/videos/{id}/stream": { "get": { "description": "Stream a visible video as direct media or an HLS response. Byte-range requests may return 206 with Content-Range, while invalid ranges return 416 and should not be retried unchanged.", "operationId": "streamVideo", "parameters": [ { "description": "The ID of the video to stream.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.apple.mpegurl": { "schema": { "description": "HLS playlist manifest.", "type": "string" } }, "video/mp4": { "schema": { "description": "200 response for api videos id stream value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "video/webm": { "schema": { "description": "200 response for api videos id stream value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Complete MP4/WebM stream or HLS manifest, depending on the stored asset.", "headers": { "Accept-Ranges": { "description": "Present for directly streamed MP4 and WebM assets.", "schema": { "example": "bytes", "type": "string" } }, "Content-Length": { "description": "Full byte length for directly streamed MP4 and WebM assets.", "schema": { "minimum": 0, "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "206": { "content": { "video/mp4": { "schema": { "description": "206 response for api videos id stream value documented for this operation. Format: binary.", "format": "binary", "type": "string" } }, "video/webm": { "schema": { "description": "206 response for api videos id stream value documented for this operation. Format: binary.", "format": "binary", "type": "string" } } }, "description": "Requested byte range from an MP4 or WebM asset.", "headers": { "Accept-Ranges": { "schema": { "enum": [ "bytes" ], "type": "string" } }, "Content-Length": { "schema": { "minimum": 0, "type": "integer" } }, "Content-Range": { "schema": { "example": "bytes 0-1048575/8388608", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "416": { "content": { "text/plain": { "schema": { "description": "416 response for api videos id stream value documented for this operation.", "type": "string" } } }, "description": "Requested byte range is outside the stored asset.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Stream a video using range requests", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123/stream' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/stream', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123/stream',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/{id}/stream.m3u8": { "get": { "description": "Return the authenticated HLS master playlist for a visible video. Clients should resolve variant asset URLs from this manifest and must not construct private storage paths.", "operationId": "getVideoHlsManifest", "parameters": [ { "description": "Id provided in the path.", "example": "example-id", "in": "path", "name": "id", "required": true, "schema": { "description": "Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.apple.mpegurl": { "schema": { "description": "200 response for api videos id stream m3u8 value documented for this operation.", "type": "string" } } }, "description": "HLS master playlist with authenticated child asset URLs.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video or manifest not found, or access denied.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "416": { "content": { "text/plain": { "schema": { "description": "416 response for api videos id stream m3u8 value documented for this operation.", "type": "string" } } }, "description": "Requested byte range is outside the stored fallback asset.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retrieve an authenticated HLS master playlist", "tags": [ "Videos" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123/stream.m3u8' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/stream.m3u8', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123/stream.m3u8',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/videos/{videoId}/comments": { "get": { "description": "List comments visible on one video using a VideosRead credential when API-key authentication is selected. Inaccessible videos do not leak comment metadata.", "operationId": "listVideoComments", "parameters": [ { "description": "The ID of the video.", "example": 1, "in": "path", "name": "videoId", "required": true, "schema": { "description": "Video Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" } ], "schema": { "items": { "$ref": "#/components/schemas/DeveloperComment" }, "type": "array" } } }, "description": "Returns an array of comments.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ {}, { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List all comments for a specific video", "tags": [ "Comments" ], "x-api-key-required-scope": "VideosRead", "x-api-key-required-scope-mask": 256, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "optional", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/videos/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/comments', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/videos/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a comment on a visible video. Clients that retry must send the original Idempotency-Key so the first successful response can be replayed safely.", "operationId": "createVideoComment", "parameters": [ { "description": "The ID of the video to comment on.", "example": 1, "in": "path", "name": "videoId", "required": true, "schema": { "description": "Video Id value documented for this operation.", "minimum": 1, "type": "integer" } }, { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" }, "parentComment": { "example": null, "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "content" ], "type": "object" } } }, "description": "Comment text and optional parent comment.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment created" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment created successfully.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create a comment on a video", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/videos/123/comments' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/comments', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/videos/123/comments',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 5, "policyId": "social-comment-write", "scope": "user, trusted API key, or client IP", "windowSeconds": 1 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/videos/{videoId}/comments/{commentId}": { "delete": { "description": "Delete a caller-owned comment from a video while validating both identifiers and ownership. Repeated calls leave the same final resource state.", "operationId": "deleteVideoComment", "parameters": [ { "description": "Video Id provided in the path.", "example": 1, "in": "path", "name": "videoId", "required": true, "schema": { "description": "Video Id value documented for this operation.", "minimum": 1, "type": "integer" } }, { "description": "Comment Id provided in the path.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Operation completed" }, "schema": { "$ref": "#/components/schemas/DeveloperMessageResponse" } } }, "description": "Comment deleted successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete a comment on a video", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/videos/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/comments/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/videos/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "patch": { "description": "Replace the editable content of the caller-owned video comment. Video visibility and comment ownership are checked independently by the runtime.", "operationId": "updateVideoComment", "parameters": [ { "description": "Video Id provided in the path.", "example": 1, "in": "path", "name": "videoId", "required": true, "schema": { "description": "Video Id value documented for this operation.", "minimum": 1, "type": "integer" } }, { "description": "Comment Id provided in the path.", "example": 1, "in": "path", "name": "commentId", "required": true, "schema": { "description": "Comment Id value documented for this operation.", "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "example": { "content": "Beautiful composition!" }, "schema": { "properties": { "content": { "example": "Beautiful composition!", "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "content" ], "type": "object" } } }, "description": "Replacement comment text.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "comment": { "author": { "id": 42, "profilePicture": null, "username": "rainbow-creator" }, "authorId": 42, "content": "Beautiful composition!", "createdAt": "2026-08-07T10:00:00.000Z", "id": 912, "isDeleted": false, "mentions": {}, "parentCommentId": null, "targetId": 108, "targetType": "IMAGE", "threadId": 912, "updatedAt": "2026-08-07T10:00:00.000Z" }, "message": "Comment updated" }, "schema": { "$ref": "#/components/schemas/DeveloperCommentMutationResponse" } } }, "description": "Comment updated successfully.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Unauthorized.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "Forbidden (not the comment author or admin).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Video or comment not found.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal server error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update an existing comment on a video", "tags": [ "Comments" ], "x-api-key-required-scope": "SocialWrite", "x-api-key-required-scope-mask": 1048576, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/videos/123/comments/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"content\":\"Beautiful composition!\"}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/videos/123/comments/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"content\": \"Beautiful composition!\"\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/videos/123/comments/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"content\\\":\\\"Beautiful composition!\\\"}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/webhooks/deliveries/{deliveryId}": { "get": { "description": "Inspect one caller-owned delivery, its event envelope, attempts, status code, and bounded response snippet.", "operationId": "getWebhookDelivery", "parameters": [ { "description": "Delivery Id provided in the path.", "example": "example-delivery-id", "in": "path", "name": "deliveryId", "required": true, "schema": { "description": "Delivery Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "attemptCount": 1, "createdAt": "2026-07-28T10:00:00.000Z", "endpointId": "value", "eventId": "evt_57d188eb4444469eaf32e6707f8f13b7", "id": "dly_2ed1c66c402a42489fa613a2a85e0eb0", "lastAttemptAt": "2026-07-28T10:00:00.000Z", "lastError": "value", "lastStatusCode": 1, "nextAttemptAt": "2026-07-28T10:00:00.000Z", "responseSnippet": "value", "status": "PENDING", "updatedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "$ref": "#/components/schemas/DeveloperWebhookDeliveryResponse" } } }, "description": "Delivery detail.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Delivery not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get one owned delivery and its event", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksRead", "x-api-key-required-scope-mask": 33554432, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/webhooks/deliveries/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/deliveries/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/webhooks/deliveries/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/webhooks/deliveries/{deliveryId}/retry": { "post": { "description": "Return one failed caller-owned delivery to the queue. Receivers must deduplicate by event or delivery identifier because delivery is at least once.", "operationId": "retryWebhookDelivery", "parameters": [ { "description": "Delivery Id provided in the path.", "example": "example-delivery-id", "in": "path", "name": "deliveryId", "required": true, "schema": { "description": "Delivery Id value documented for this operation.", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "data": { "attemptCount": 1, "createdAt": "2026-07-28T10:00:00.000Z", "endpointId": "value", "eventId": "evt_57d188eb4444469eaf32e6707f8f13b7", "id": "dly_2ed1c66c402a42489fa613a2a85e0eb0", "lastAttemptAt": "2026-07-28T10:00:00.000Z", "lastError": "value", "lastStatusCode": 1, "nextAttemptAt": "2026-07-28T10:00:00.000Z", "responseSnippet": "value", "status": "PENDING", "updatedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "$ref": "#/components/schemas/DeveloperWebhookDeliveryResponse" } } }, "description": "Delivery returned to the pending queue.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Delivery not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Only failed deliveries can be retried", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Retry one failed owned delivery", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksWrite", "x-api-key-required-scope-mask": 67108864, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/webhooks/deliveries/123/retry' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/deliveries/123/retry', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/webhooks/deliveries/123/retry',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/webhooks/endpoints": { "get": { "description": "List webhook endpoints owned by the authenticated caller. Signing-secret material and every other user’s endpoints are always excluded.", "operationId": "listWebhookEndpoints", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": [] }, "schema": { "description": "Fields describing 200 response for api webhooks endpoints in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api webhooks endpoints; an empty list means none are available.", "items": { "$ref": "#/components/schemas/DeveloperWebhookEndpoint" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Owner-isolated endpoint list.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List owned webhook endpoints", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksRead", "x-api-key-required-scope-mask": 33554432, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/webhooks/endpoints' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/webhooks/endpoints',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "post": { "description": "Create a disabled endpoint for an HTTPS port-443 receiver. The signing secret is returned exactly once; store it before completing URL verification.", "operationId": "createWebhookEndpoint", "parameters": [ { "description": "Visible ASCII key, 1-128 characters. Successful responses are retained per caller, method, and target path for 24 hours.", "example": "request-018f47f2-97e2-7a32-a693-3b1bc30c6ca8", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7E]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "eventTypes": [ "model.published" ], "name": "Production events", "url": "https://example.com/webhooks/arcenciel" }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "eventTypes": { "description": "Ordered event types entries included with this request payload; an empty list means none are available.", "items": { "description": "Event Types item associated with this event types; preserve server-returned values when passing them to another operation.", "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "name": { "description": "Human-readable name for this request payload; it is not a stable identifier. Maximum length: 100 characters.", "maxLength": 100, "type": "string" }, "url": { "description": "URL for the url associated with this request payload; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "type": "string" } }, "required": [ "name", "url", "eventTypes" ], "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "data": { "autoDisabledAt": null, "consecutiveFailureCount": 0, "createdAt": "2026-08-08T00:00:00Z", "enabled": false, "eventTypes": [ "model.published" ], "id": "4b2db59e-8097-45b6-8f1c-7864e570c681", "lastDeliveredAt": null, "lastError": null, "name": "Production events", "secretLastRotatedAt": "2026-08-08T00:00:00Z", "updatedAt": "2026-08-08T00:00:00Z", "url": "https://example.com/webhooks/arcenciel", "verifiedAt": null }, "secret": "whsec_example_once_only" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/DeveloperWebhookEndpointResponse" }, { "description": "Fields describing 201 response for api webhooks endpoints in Developer API requests and responses.", "properties": { "secret": { "description": "Secret associated with this 201 response for api webhooks endpoints; preserve server-returned values when passing them to another operation.", "example": "whsec_example_once_only", "type": "string" } }, "required": [ "secret" ], "type": "object" } ], "description": "201 response for api webhooks endpoints value documented for this operation." } } }, "description": "Endpoint plus its one-time signing secret.", "headers": { "Idempotency-Replayed": { "description": "True when the original successful response was replayed for this Idempotency-Key.", "schema": { "example": true, "type": "boolean" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid endpoint input", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency key conflicts with another payload or is still in progress.", "errorCode": "IDEMPOTENCY_KEY_REUSED", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Endpoint limit reached The idempotency key conflicts with another payload or is still in progress.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "content": { "application/json": { "examples": { "idempotency": { "summary": "Idempotency protection error", "value": { "error": "The idempotency service is temporarily unavailable; retry later with the same key.", "errorCode": "IDEMPOTENCY_UNAVAILABLE", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The idempotency service is temporarily unavailable; retry later with the same key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Create an unverified webhook endpoint", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksWrite", "x-api-key-required-scope-mask": 67108864, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/webhooks/endpoints' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"name\":\"Production events\",\"url\":\"https://example.com/webhooks/arcenciel\",\"eventTypes\":[\"model.published\"]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"name\": \"Production events\",\n \"url\": \"https://example.com/webhooks/arcenciel\",\n \"eventTypes\": [\n \"model.published\"\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/webhooks/endpoints',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"name\\\":\\\"Production events\\\",\\\"url\\\":\\\"https://example.com/webhooks/arcenciel\\\",\\\"eventTypes\\\":[\\\"model.published\\\"]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotency-key" } }, "/api/webhooks/endpoints/{endpointId}": { "delete": { "description": "Delete one caller-owned endpoint and its retained delivery history. Repeating the logical deletion is safe for clients.", "operationId": "deleteWebhookEndpoint", "parameters": [ { "description": "endpointId path identifier.", "example": "example", "in": "path", "name": "endpointId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "204": { "description": "Endpoint and its delivery history deleted", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Endpoint not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Delete one owned webhook endpoint", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksWrite", "x-api-key-required-scope-mask": 67108864, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request DELETE \\\n --url 'https://arcenciel.io/api/webhooks/endpoints/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints/123', {\n method: 'DELETE',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'DELETE',\n 'https://arcenciel.io/api/webhooks/endpoints/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 20, "policyId": "standard-delete", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 40, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" }, "get": { "description": "Read one caller-owned endpoint and its bounded health state without exposing signing secrets.", "operationId": "getWebhookEndpoint", "parameters": [ { "description": "endpointId path identifier.", "example": "example", "in": "path", "name": "endpointId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "autoDisabledAt": "2026-07-28T10:00:00.000Z", "consecutiveFailureCount": 1, "createdAt": "2026-07-28T10:00:00.000Z", "enabled": true, "eventTypes": [ "model.published" ], "id": "4b2db59e-8097-45b6-8f1c-7864e570c681", "lastDeliveredAt": "2026-07-28T10:00:00.000Z", "lastError": "value", "name": "Production events", "secretLastRotatedAt": "2026-07-28T10:00:00.000Z", "updatedAt": "2026-07-28T10:00:00.000Z", "url": "https://example.com/webhooks/arcenciel", "verifiedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "$ref": "#/components/schemas/DeveloperWebhookEndpointResponse" } } }, "description": "Endpoint details without signing-secret material.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Endpoint not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Get one owned webhook endpoint", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksRead", "x-api-key-required-scope-mask": 33554432, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/webhooks/endpoints/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints/123', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/webhooks/endpoints/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" }, "patch": { "description": "Update endpoint metadata, subscriptions, state, or URL. A URL change disables the endpoint and requires a fresh verification challenge.", "operationId": "updateWebhookEndpoint", "parameters": [ { "description": "endpointId path identifier.", "example": "example", "in": "path", "name": "endpointId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "enabled": false, "eventTypes": [ "model.published", "article.published" ] }, "schema": { "description": "Fields describing request payload in Developer API requests and responses.", "properties": { "enabled": { "description": "Whether enabled applies to this request payload.", "type": "boolean" }, "eventTypes": { "description": "Ordered event types entries included with this request payload; an empty list means none are available.", "items": { "description": "Event Types item associated with this event types; preserve server-returned values when passing them to another operation.", "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "name": { "description": "Human-readable name for this request payload; it is not a stable identifier. Maximum length: 100 characters.", "maxLength": 100, "type": "string" }, "url": { "description": "URL for the url associated with this request payload; do not persist temporary signed query parameters. Format: uri.", "format": "uri", "type": "string" } }, "type": "object" } } }, "description": "Request payload for this operation.", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "autoDisabledAt": "2026-07-28T10:00:00.000Z", "consecutiveFailureCount": 1, "createdAt": "2026-07-28T10:00:00.000Z", "enabled": true, "eventTypes": [ "model.published" ], "id": "4b2db59e-8097-45b6-8f1c-7864e570c681", "lastDeliveredAt": "2026-07-28T10:00:00.000Z", "lastError": "value", "name": "Production events", "secretLastRotatedAt": "2026-07-28T10:00:00.000Z", "updatedAt": "2026-07-28T10:00:00.000Z", "url": "https://example.com/webhooks/arcenciel", "verifiedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "$ref": "#/components/schemas/DeveloperWebhookEndpointResponse" } } }, "description": "Updated endpoint.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Invalid update", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Endpoint not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Endpoint must be verified before enabling", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Update one owned webhook endpoint", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksWrite", "x-api-key-required-scope-mask": 67108864, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request PATCH \\\n --url 'https://arcenciel.io/api/webhooks/endpoints/123' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY' \\\n -H 'Content-Type: application/json' \\\n --data '{\"enabled\":false,\"eventTypes\":[\"model.published\",\"article.published\"]}'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints/123', {\n method: 'PATCH',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY!, 'Content-Type': 'application/json' },\n body: JSON.stringify({\n \"enabled\": false,\n \"eventTypes\": [\n \"model.published\",\n \"article.published\"\n ]\n}),\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport json\nimport httpx\n\nresponse = httpx.request(\n 'PATCH',\n 'https://arcenciel.io/api/webhooks/endpoints/123',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n json=json.loads(\"{\\\"enabled\\\":false,\\\"eventTypes\\\":[\\\"model.published\\\",\\\"article.published\\\"]}\"),\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "idempotent" } }, "/api/webhooks/endpoints/{endpointId}/deliveries": { "get": { "description": "List 30-day delivery history for one caller-owned endpoint using an opaque cursor. Response bodies are truncated and must not be treated as a receiver log.", "operationId": "listWebhookDeliveries", "parameters": [ { "description": "Endpoint Id provided in the path.", "example": "example-endpoint-id", "in": "path", "name": "endpointId", "required": true, "schema": { "description": "Endpoint Id value documented for this operation.", "type": "string" } }, { "description": "Cursor provided in the query.", "example": "next-page", "in": "query", "name": "cursor", "schema": { "description": "Cursor value documented for this operation.", "type": "string" } }, { "description": "Limit provided in the query.", "example": 25, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Limit value documented for this operation. Minimum: 1. Maximum: 100.", "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [], "nextCursor": null }, "schema": { "description": "Fields describing 200 response for api webhooks endpoints endpoint id deliveries in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api webhooks endpoints endpoint id deliveries; an empty list means none are available.", "items": { "$ref": "#/components/schemas/DeveloperWebhookDelivery" }, "type": "array" }, "nextCursor": { "description": "Opaque continuation token for the next page of this 200 response for api webhooks endpoints endpoint id deliveries; absent or null means iteration is complete.", "nullable": true, "type": "string" } }, "required": [ "data", "nextCursor" ], "type": "object" } } }, "description": "Cursor-paginated delivery history retained for 30 days.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Endpoint not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List deliveries for one owned endpoint", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksRead", "x-api-key-required-scope-mask": 33554432, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/webhooks/endpoints/123/deliveries' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints/123/deliveries', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/webhooks/endpoints/123/deliveries',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } }, "/api/webhooks/endpoints/{endpointId}/rotate-secret": { "post": { "description": "Generate a new one-time signing secret while retaining the previous signature for a 24-hour overlap. Do not retry automatically after an ambiguous response.", "operationId": "rotateWebhookSecret", "parameters": [ { "description": "Endpoint Id provided in the path.", "example": "example-endpoint-id", "in": "path", "name": "endpointId", "required": true, "schema": { "description": "Endpoint Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "autoDisabledAt": "2026-07-28T10:00:00.000Z", "consecutiveFailureCount": 1, "createdAt": "2026-07-28T10:00:00.000Z", "enabled": true, "eventTypes": [ "model.published" ], "id": "4b2db59e-8097-45b6-8f1c-7864e570c681", "lastDeliveredAt": "2026-07-28T10:00:00.000Z", "lastError": "value", "name": "Production events", "secretLastRotatedAt": "2026-07-28T10:00:00.000Z", "updatedAt": "2026-07-28T10:00:00.000Z", "url": "https://example.com/webhooks/arcenciel", "verifiedAt": "2026-07-28T10:00:00.000Z" }, "previousSecretExpiresAt": "2026-07-28T10:00:00.000Z", "secret": "value" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/DeveloperWebhookEndpointResponse" }, { "description": "Fields describing 200 response for api webhooks endpoints endpoint id rotate secret in Developer API requests and responses.", "properties": { "previousSecretExpiresAt": { "description": "UTC timestamp for the previous secret expires at transition of this 200 response for api webhooks endpoints endpoint id rotate secret. Format: date-time.", "format": "date-time", "type": "string" }, "secret": { "description": "Secret associated with this 200 response for api webhooks endpoints endpoint id rotate secret; preserve server-returned values when passing them to another operation.", "type": "string" } }, "required": [ "secret", "previousSecretExpiresAt" ], "type": "object" } ], "description": "200 response for api webhooks endpoints endpoint Id rotate secret value documented for this operation." } } }, "description": "Endpoint, one-time new secret, and old-secret expiry.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Endpoint not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Rotate the signing secret with 24-hour overlap", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksWrite", "x-api-key-required-scope-mask": 67108864, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/webhooks/endpoints/123/rotate-secret' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints/123/rotate-secret', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/webhooks/endpoints/123/rotate-secret',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/webhooks/endpoints/{endpointId}/test": { "post": { "description": "Queue a signed webhook.test delivery through the normal dispatcher so receivers can validate headers and duplicate handling.", "operationId": "testWebhookEndpoint", "parameters": [ { "description": "Endpoint Id provided in the path.", "example": "example-endpoint-id", "in": "path", "name": "endpointId", "required": true, "schema": { "description": "Endpoint Id value documented for this operation.", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "data": { "deliveryId": "dly_example", "eventId": "evt_example", "status": "PENDING" } }, "schema": { "description": "Fields describing 202 response for api webhooks endpoints endpoint id test in Developer API requests and responses.", "properties": { "data": { "description": "Structured data details for this 202 response for api webhooks endpoints endpoint id test.", "properties": { "deliveryId": { "description": "Stable identifier for the delivery; use it in subsequent API calls instead of a display name.", "type": "string" }, "eventId": { "description": "Stable identifier for the event; use it in subsequent API calls instead of a display name.", "type": "string" }, "status": { "description": "Current lifecycle state of this data; clients should tolerate future values. Supported values: `PENDING`.", "enum": [ "PENDING" ], "type": "string" } }, "required": [ "eventId", "deliveryId", "status" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Test delivery accepted.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Endpoint not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "409": { "description": "Endpoint is not active", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Queue a signed test delivery", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksWrite", "x-api-key-required-scope-mask": 67108864, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/webhooks/endpoints/123/test' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints/123/test', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/webhooks/endpoints/123/test',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/webhooks/endpoints/{endpointId}/verify": { "post": { "description": "Send a one-time URL-verification challenge. The receiver must return the exact challenge in a successful JSON response before deliveries are enabled.", "operationId": "verifyWebhookEndpoint", "parameters": [ { "description": "Endpoint Id provided in the path.", "example": "example-endpoint-id", "in": "path", "name": "endpointId", "required": true, "schema": { "description": "Endpoint Id value documented for this operation.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": { "autoDisabledAt": "2026-07-28T10:00:00.000Z", "consecutiveFailureCount": 1, "createdAt": "2026-07-28T10:00:00.000Z", "enabled": true, "eventTypes": [ "model.published" ], "id": "4b2db59e-8097-45b6-8f1c-7864e570c681", "lastDeliveredAt": "2026-07-28T10:00:00.000Z", "lastError": "value", "name": "Production events", "secretLastRotatedAt": "2026-07-28T10:00:00.000Z", "updatedAt": "2026-07-28T10:00:00.000Z", "url": "https://example.com/webhooks/arcenciel", "verifiedAt": "2026-07-28T10:00:00.000Z" } }, "schema": { "$ref": "#/components/schemas/DeveloperWebhookEndpointResponse" } } }, "description": "Verified and enabled endpoint.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "400": { "description": "Endpoint URL is no longer safe", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "404": { "description": "Endpoint not found", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "422": { "description": "Challenge response did not validate", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "Verify ownership and reachability using a challenge", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksWrite", "x-api-key-required-scope-mask": 67108864, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request POST \\\n --url 'https://arcenciel.io/api/webhooks/endpoints/123/verify' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/endpoints/123/verify', {\n method: 'POST',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'POST',\n 'https://arcenciel.io/api/webhooks/endpoints/123/verify',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 120, "policyId": "standard-write", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 240, "windowSeconds": 60 }, "x-sdk-retry-classification": "no-automatic-retry" } }, "/api/webhooks/event-types": { "get": { "description": "List the public event names and payload versions supported by Developer Webhooks. Discover this catalog instead of using undocumented staff event names.", "operationId": "listWebhookEventTypes", "parameters": [], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "description": "A model became public.", "type": "model.published", "version": "1" } ] }, "schema": { "description": "Fields describing 200 response for api webhooks event types in Developer API requests and responses.", "properties": { "data": { "description": "Ordered data entries included with this 200 response for api webhooks event types; an empty list means none are available.", "items": { "$ref": "#/components/schemas/DeveloperWebhookEventType" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Versioned event types.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "401": { "description": "Authentication required", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "403": { "description": "API key is valid but does not include the required scope.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] }, { "sessionCookieAuth": [] }, { "apiKeyAuth": [] } ], "summary": "List supported webhook event types", "tags": [ "Webhooks" ], "x-api-key-required-scope": "WebhooksRead", "x-api-key-required-scope-mask": 33554432, "x-arcenciel-audience": "public", "x-arcenciel-auth": { "mode": "required", "schemes": [ "apiKeyAuth", "bearerAuth", "sessionCookieAuth" ] }, "x-arcenciel-contract-version": 1, "x-arcenciel-stability": "stable", "x-arcenciel-surfaces": [ "backend" ], "x-codeSamples": [ { "label": "cURL", "lang": "cURL", "source": "curl --request GET \\\n --url 'https://arcenciel.io/api/webhooks/event-types' \\\n -H 'x-api-key: $ARCENCIEL_API_KEY'" }, { "label": "TypeScript fetch", "lang": "TypeScript", "source": "const response = await fetch('https://arcenciel.io/api/webhooks/event-types', {\n method: 'GET',\n headers: { 'x-api-key': process.env.ARCENCIEL_API_KEY! },\n});\nif (!response.ok) throw new Error(`Arc en Ciel request failed: ${response.status}`);" }, { "label": "Python httpx", "lang": "Python", "source": "import os\nimport httpx\n\nresponse = httpx.request(\n 'GET',\n 'https://arcenciel.io/api/webhooks/event-types',\n headers={'x-api-key': os.environ['ARCENCIEL_API_KEY']},\n timeout=30.0,\n)\nresponse.raise_for_status()" } ], "x-rate-limit-policy": { "limit": 1200, "policyId": "standard-read", "scope": "user, trusted API key, or client IP", "trustedApiKeyLimit": 2400, "windowSeconds": 60 }, "x-sdk-retry-classification": "safe" } } }, "security": [], "servers": [ { "url": "https://arcenciel.io" } ], "tags": [ { "description": "Stable public model discovery and metadata operations.", "name": "Models" }, { "description": "Stable file inspection, transfer, and download-registration operations.", "name": "Downloads" }, { "description": "Stable public article discovery and article-media operations.", "name": "Articles" }, { "description": "Stable public profile, creator statistics, and upload-discovery operations.", "name": "Users" }, { "description": "Stable anonymous catalogue reads for public community emotes.", "name": "Emotes" }, { "description": "Stable public image discovery, metadata, analysis, and transfer operations.", "name": "Images" }, { "description": "Stable anonymous catalogue reads for tag usage and discovery.", "name": "Tags" }, { "description": "Stable public video discovery, metadata, streaming, and transfer operations.", "name": "Videos" }, { "description": "Stable collection discovery, detail, and manager contribution-request reads.", "name": "Collections" }, { "description": "Stable live and historical collaboration discovery, detail, and showcase operations.", "name": "Collabs" }, { "description": "Stable reads and authenticated comment creation, editing, and removal.", "name": "Comments" }, { "description": "Stable favorites, reactions, follows, and related personal social state.", "name": "Social" }, { "description": "Stable current-user notification reads and read-state management.", "name": "Notifications" }, { "description": "Stable current-user profile, preference, history, upload, and export operations.", "name": "Profile" }, { "description": "Stable image and video generation discovery, job, output, and preset workflows.", "name": "Generator" }, { "description": "Stable private conversation, request, group, message, reaction, and read-state workflows.", "name": "Chat" }, { "description": "Stable caller-owned product feedback, attachment, and deletion workflows.", "name": "Feedback" }, { "description": "Stable privacy-filtered illegal-content notice, evidence, review-request, and content-report workflows.", "name": "Trust & Safety" }, { "description": "Stable owner-scoped event endpoint, verification, signing, delivery diagnostic, and retry workflows.", "name": "Webhooks" } ], "x-arcenciel-audience": "public", "x-arcenciel-lifecycle": { "deprecationNoticeDays": 180, "policyUrl": "https://arcenciel.io/developers#lifecycle", "previousMajorSupportDays": 365, "stability": "stable" }, "x-arcenciel-pagination": { "cursor": { "completion": "Stop when nextCursor is null or absent; cursor values are opaque and must be passed back unchanged.", "requestFields": [ "cursor", "limit" ], "responseFields": [ "data", "nextCursor" ], "sdkHelper": "paginateCursor" }, "page": { "completion": "Stop after totalPages or when an empty page is returned.", "requestFields": [ "page", "limit" ], "responseFields": [ "data", "page", "limit", "totalPages", "totalCount" ], "sdkHelper": "paginatePages" } }, "x-arcenciel-profile": "developer-v1", "x-arcenciel-surfaces": [ "backend", "upload-edge" ], "x-arcenciel-versioning": { "compatibility": "Additive v1 releases preserve existing clients; breaking changes require a parallel v2 migration surface.", "lifecyclePolicy": "https://arcenciel.io/developers#lifecycle", "majorContract": "v1", "releaseManifest": "https://arcenciel.io/developers/openapi/releases.json", "runtimePathPrefix": "/api", "strategy": "immutable-contract", "versionedRuntimePathPrefix": false }, "x-arcenciel-webhooks": { "delivery": { "deduplicationField": "id", "maximumAttempts": 5, "orderingGuaranteed": false, "receiverTimeoutSeconds": 10, "semantics": "at-least-once" }, "eventContract": "https://arcenciel.io/developers/asyncapi-v1", "guide": "https://arcenciel.io/developers/webhooks/reference", "managementBasePath": "/api/webhooks", "signature": { "algorithm": "HMAC-SHA256", "digestEncoding": "lowercase hexadecimal", "example": "t=1786147200,v1=59367d...c18a", "headerName": "X-AEC-Signature", "pythonVerifier": "verify_webhook_signature(raw_body, signature_header, signing_secret)", "rotationOverlapSeconds": 86400, "signatureField": "v1", "signedPayload": ".", "timestampField": "t", "toleranceSeconds": 300, "typescriptVerifier": "verifyWebhookSignature(rawBody, signatureHeader, signingSecret)" } } }