{"openapi":"3.1.0","info":{"title":"ioy.ai API","version":"1.5.0","description":"Session or scoped Bearer key. Reuse the same operation key when retrying an identical request. Unknown tasks retain held credits and require reconciliation."},"servers":[{"url":"https://ioy.ai"}],"paths":{"/api/v1/jobs":{"get":{"operationId":"listJobs","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]},"post":{"operationId":"createJob","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"202":{"description":"Task queued","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Operation key conflicts with different input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["text","image","audio","chat","image-edit","image-caption","web-search"]},"prompt":{"type":"string","minLength":3,"maxLength":8000},"inputAssetId":{"type":"string","description":"Private image ID returned by uploadFile; required for image-edit and image-caption."},"conversationId":{"type":"string","description":"User-owned conversation ID required for chat."}},"required":["kind","prompt"]}}}}}},"/api/v1/jobs/{id}":{"get":{"operationId":"getJob","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"}}}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/api/v1/jobs/{id}/result":{"get":{"operationId":"downloadResult","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/octet-stream":{"schema":{"type":"string","contentEncoding":"binary"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/api/v1/quota":{"get":{"operationId":"getQuota","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quota"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]}},"/api/template/access":{"get":{"operationId":"getTemplateRelease","summary":"Get available sanitized template release and clone URL.","description":"Template website only; disabled in generated products.","security":[{"websiteSession":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"Sign in required"},"403":{"description":"Verified website session or valid origin required"},"404":{"description":"Template access disabled"},"503":{"description":"Release unavailable"}}},"post":{"operationId":"createTemplateCloneCredential","summary":"Create a one-hour read-only clone credential. Replaces older credentials; shown once. Requires same-origin browser request.","description":"Template website only; disabled in generated products.","security":[{"websiteSession":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"Sign in required"},"403":{"description":"Verified website session or valid origin required"},"404":{"description":"Template access disabled"},"503":{"description":"Release unavailable"}}},"delete":{"operationId":"revokeTemplateCloneCredential","summary":"Revoke current user clone credentials. Requires same-origin browser request.","description":"Template website only; disabled in generated products.","security":[{"websiteSession":[]}],"responses":{"200":{"description":"Successful response"},"401":{"description":"Sign in required"},"403":{"description":"Verified website session or valid origin required"},"404":{"description":"Template access disabled"},"503":{"description":"Release unavailable"}}}},"/api/v1/conversations":{"get":{"operationId":"listConversations","security":[{"bearerAuth":[]}],"description":"Requires jobs:read. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}},"required":["items"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]},"post":{"operationId":"createConversation","security":[{"bearerAuth":[]}],"description":"Requires jobs:write. User-scoped data; keys never appear in responses.","responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/Conversation"}},"required":["conversation"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Stable operation key for identical retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":100}}}}}}}},"/api/v1/conversations/{id}":{"get":{"operationId":"getConversation","security":[{"bearerAuth":[]}],"description":"Requires jobs:read. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}},"required":["conversation","items"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"operationId":"renameConversation","security":[{"bearerAuth":[]}],"description":"Requires jobs:write. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"}},"required":["updated"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":100}},"required":["title"]}}}}},"delete":{"operationId":"deleteConversation","security":[{"bearerAuth":[]}],"description":"Requires jobs:write. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/conversations/{id}/messages":{"post":{"operationId":"sendMessage","security":[{"bearerAuth":[]}],"description":"Requires jobs:write. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Existing identical task reused","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"},"reused":{"type":"boolean"}},"required":["job","reused"]}}}},"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"},"reused":{"type":"boolean"}},"required":["job","reused"]}},"text/event-stream":{"schema":{"type":"string"},"description":"When Accept: text/event-stream is sent, emits job, token and done events."}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Stable operation key for identical retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":8000}},"required":["prompt"]}}}}}},"/api/v1/files":{"get":{"operationId":"listFiles","security":[{"bearerAuth":[]}],"description":"Requires files:read. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/File"}}},"required":["items"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]},"post":{"operationId":"uploadFile","security":[{"bearerAuth":[]}],"description":"Requires files:write. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Identical upload reused","content":{"application/json":{"schema":{"type":"object","required":["id","status","reused"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ready","pending"]},"reused":{"type":"boolean"}}}}}},"201":{"description":"Private upload ready","content":{"application/json":{"schema":{"type":"object","required":["id","status","reused"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ready","pending"]},"reused":{"type":"boolean"}}}}}},"202":{"description":"Object acceptance unconfirmed; query metadata or retry identical input with original key","content":{"application/json":{"schema":{"type":"object","required":["id","status","reused"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ready","pending"]},"reused":{"type":"boolean"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Deleted or expired upload receipt; use a new key for a new file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Upload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported MIME or signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-File-Name","in":"header","schema":{"type":"string","maxLength":100}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Stable upload key. Without one, server derives a key from file contents, MIME and name. Changed input conflicts409."}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string","format":"binary"}}}}}},"/api/v1/files/{id}":{"get":{"operationId":"downloadFile","security":[{"bearerAuth":[]}],"description":"Requires files:read. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Private attachment","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"operationId":"deleteFile","security":[{"bearerAuth":[]}],"description":"Requires files:write. User-scoped data; keys never appear in responses.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or verified email missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting input or active/unknown conversation turn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/files/{id}/metadata":{"get":{"operationId":"getFileMetadata","security":[{"bearerAuth":[]}],"description":"Requires files:read. Reconcile pending objects by original content hash. Query form ?metadata=1 also supported.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Private upload metadata","content":{"application/json":{"schema":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"mime":{"type":"string"},"size":{"type":"integer"},"status":{"type":"string","enum":["ready","pending"]}}}}}},"404":{"description":"Private file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Stored bytes mismatch original receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Upload deleted or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/keys/current":{"delete":{"operationId":"revokeCurrentKey","summary":"Revoke only the API key authorizing this request","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}},"required":["revoked"]}}}},"403":{"description":"Website session cannot revoke an unspecified device key"}}}},"/api/v1/trends":{"get":{"operationId":"listTrends","description":"Optional trend module; disabled modules return 404. Only active workflows are publicly listed.","security":[],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Trend"}}},"required":["items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Module, active workflow, or owned job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/trends/{slug}":{"get":{"operationId":"getTrend","description":"Optional trend module; disabled modules return 404. Only active workflows are publicly listed.","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"trend":{"$ref":"#/components/schemas/Trend"}},"required":["trend"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Module, active workflow, or owned job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/trends/{slug}/jobs":{"get":{"operationId":"listTrendJobs","description":"Requires jobs:read. Optional trend module; disabled modules return 404. Only active workflows are publicly listed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TrendJob"}}},"required":["items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Module, active workflow, or owned job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs:read"},"post":{"operationId":"createTrendJob","description":"Requires jobs:write. Optional trend module; disabled modules return 404. Only active workflows are publicly listed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Identical operation key reused; no second reservation","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/TrendJob"},"reused":{"type":"boolean"}},"required":["job","reused"]}}}},"202":{"description":"Task queued","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/TrendJob"},"reused":{"type":"boolean"}},"required":["job","reused"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Module, active workflow, or owned job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Operation key conflicts with different input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Live provider, costs, storage or durable workflow is not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"type":"string"},"inputs":{"type":"object","additionalProperties":{"type":"string"},"description":"Declared input IDs mapped to user-owned ready private image asset IDs."}},"required":["inputs"]}}}}}},"/api/v1/trends/{slug}/jobs/{id}":{"get":{"operationId":"getTrendJob","description":"Requires jobs:read. Optional trend module; disabled modules return 404. Only active workflows are publicly listed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/TrendJob"}},"required":["job"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Module, active workflow, or owned job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs:read"}},"/api/v1/trends/{slug}/jobs/{id}/result":{"get":{"operationId":"downloadTrendResult","description":"Requires jobs:read. Optional trend module; disabled modules return 404. Only active workflows are publicly listed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Confirmed final private video, bounded by product.limits.maxResultBytes","content":{"video/mp4":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Module, active workflow, or owned job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Final video is not confirmed successful yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"jobs:read"}},"/api/admin/site-stats":{"get":{"operationId":"getAdminSiteStats","summary":"Read a daily website statistics aggregate","description":"Requires an allowlisted administrator website session, recent login and, outside local development, second-factor verification. Product Bearer API keys cannot access this operation. Dates use Asia/Shanghai. Anonymous traffic is retained for 90 days; older queries return trafficState=expired, rather than claiming zero actual traffic. Defaults to the previous calendar day. This returns the current aggregate, which may differ from a saved email snapshot after account deletion or late events.","security":[{"websiteSession":[]}],"parameters":[{"name":"day","in":"query","required":false,"description":"Calendar day in Asia/Shanghai; omitted means yesterday.","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Current daily aggregate and collection coverage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStats"}}}},"400":{"description":"Invalid calendar date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Website session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Administrator, recent login or second-factor verification required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/site-stats/send":{"post":{"operationId":"sendAdminSiteStats","summary":"Send a saved daily statistics report to the configured operator recipient","description":"Requires an allowlisted administrator website session, recent login and, outside local development, second-factor verification. Product Bearer API keys cannot access this operation. Dates use Asia/Shanghai. Anonymous traffic is retained for 90 days; older dates are rejected. Same-origin request required. Only completed calendar days may be sent. The configured recipient cannot be overridden by this request. One immutable snapshot and outbox operation are used per site, day and recipient, regardless of the request Idempotency-Key. A sent state means provider acceptance, not inbox delivery; Cloudflare unknown acceptance is not automatically resent.","security":[{"websiteSession":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Administrator operation key. Report identity is independently fixed by site, day and configured recipient.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[\\w:-]{8,128}$"}},{"name":"Origin","in":"header","required":true,"description":"Exact configured application origin; supplied automatically by same-origin browser requests.","schema":{"type":"string","format":"uri"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Completed calendar day in Asia/Shanghai; omitted means yesterday."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Existing or newly submitted outbox operation; null when statistics or recipient are disabled. Provider acceptance and inbox delivery are separate states.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SiteStatsDispatch"},{"type":"null"}]}}}},"400":{"description":"Invalid/incomplete date, date outside retention, or missing/invalid operation key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Website session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Administrator, recent login, second-factor verification or same-origin check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Statistics recipient or email provider is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"websiteSession":{"type":"apiKey","in":"cookie","name":"__Secure-cioy.session_token","description":"Verified template-website session; local development uses cioy.session_token. Product Bearer keys cannot claim template access."}},"schemas":{"Job":{"type":"object","required":["id","kind","status"],"properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","unknown","canceled"]},"text":{"type":["string","null"]},"resultUrl":{"type":["string","null"]},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"prompt":{"type":"string"},"conversationId":{"type":["string","null"]},"inputAssetId":{"type":["string","null"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SearchSource"}},"model":{"type":["string","null"]},"units":{"type":["number","null"]},"costMicros":{"type":["integer","null"]},"inputUnits":{"type":["number","null"]},"outputUnits":{"type":["number","null"]},"updatedAt":{"type":"string","format":"date-time"}}},"Quota":{"type":"object","properties":{"available":{"type":"integer","minimum":0},"held":{"type":"integer","minimum":0},"consumed":{"type":"integer","minimum":0}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"SearchSource":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}},"Conversation":{"type":"object","required":["id","title","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"File":{"type":"object","required":["id","name","mime","size"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"mime":{"type":"string"},"size":{"type":"integer"},"created_at":{"type":"string"},"expires_at":{"type":"string"}}},"TrendVariant":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"resolution":{"type":"string","enum":["480p","720p","1080p"]},"duration":{"type":"integer","minimum":1},"credits":{"type":"integer","minimum":1},"estimatedSeconds":{"type":"integer","minimum":1}},"required":["id","label","resolution","duration","credits"]},"TrendInput":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["image","text"]},"required":{"type":"boolean"},"count":{"type":"integer"},"accept":{"type":"string"},"maxSize":{"type":"integer","minimum":1},"placeholder":{"type":"string"}},"required":["id","label","kind"]},"Trend":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","const":"active"},"category":{"type":"string"},"seo":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"]}}},"required":["title","description"]},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/TrendInput"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/TrendVariant"}},"defaultVariant":{"type":"string"},"example":{"type":"object","properties":{"poster":{"type":"string"},"video":{"type":"string"},"thumbnail":{"type":"string"}}},"musicHint":{"type":"string"},"estimatedDurationSeconds":{"type":"integer"}},"required":["slug","name","status","seo","variants","defaultVariant","example"]},"TrendStep":{"type":"object","properties":{"id":{"type":"string"},"stepId":{"type":"string"},"type":{"type":"string","enum":["image-edit","image-to-video"]},"status":{"type":"string","enum":["pending","running","succeeded","failed","unknown"]},"outputAssetId":{"type":["string","null"]},"error":{"type":["string","null"]}},"required":["id","stepId","type","status"]},"TrendJob":{"type":"object","properties":{"id":{"type":"string"},"trendSlug":{"type":"string"},"variantId":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","unknown"]},"currentStep":{"type":"integer"},"totalSteps":{"type":"integer"},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"outputs":{"anyOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"steps":{"type":"array","items":{"$ref":"#/components/schemas/TrendStep"}}},"required":["id","trendSlug","variantId","status","currentStep","totalSteps","error","createdAt","updatedAt","completedAt","outputs"]},"SiteStats":{"type":"object","required":["day","timezone","site","collectionStartedAt","trafficState","pageviews","visitors","registrations","signedInUsers","templateClaims","templateDownloads","fileDownloads","skillDownloads","topPages"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"timezone":{"type":"string","const":"Asia/Shanghai"},"site":{"type":"string","format":"uri"},"collectionStartedAt":{"type":["string","null"],"format":"date-time"},"trafficState":{"type":"string","enum":["disabled","not_collected","partial","complete","expired"],"description":"Coverage of first-party public-page traffic. Expired means the date is outside the 90-day anonymous traffic retention window. Missing or expired collection must not be interpreted as zero actual traffic."},"pageviews":{"type":"integer","minimum":0,"description":"Recorded public page views; scripts, privacy signals and recognized bots affect coverage."},"visitors":{"type":"integer","minimum":0,"description":"Daily browser-token deduplication, independent of accounts and GA4."},"registrations":{"type":"object","required":["total","newUsers","verified"],"properties":{"total":{"type":"integer","minimum":0,"description":"Currently retained accounts created before the end of this day."},"newUsers":{"type":"integer","minimum":0,"description":"Currently retained accounts created within this day."},"verified":{"type":"integer","minimum":0,"description":"Currently email-verified accounts among total."}}},"signedInUsers":{"type":"integer","minimum":0,"description":"Distinct retained accounts with trusted login events on this day."},"templateClaims":{"type":"integer","minimum":0,"description":"Successful credential claims, deduplicated per retained account, release and day."},"templateDownloads":{"type":"integer","minimum":0,"description":"Authorized full Git pack GET starts, deduplicated per retained account, release and day; client completion is not proven."},"fileDownloads":{"type":"integer","minimum":0,"description":"Authorized private file full GET response starts; HEAD, Range and failed lookups excluded."},"skillDownloads":{"type":"integer","minimum":0,"description":"Public Skill ZIP full download response starts; not installation completion."},"topPages":{"type":"array","maxItems":10,"items":{"type":"object","required":["path","views"],"properties":{"path":{"type":"string"},"views":{"type":"integer","minimum":0}}}}}},"SiteStatsDispatch":{"type":"object","required":["day","id","state","delivery_state"],"properties":{"day":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"id":{"type":"string","description":"Deterministic outbox operation identifier."},"state":{"type":"string","enum":["queued","sending","sent","unknown","failed"]},"delivery_state":{"type":["string","null"],"description":"Provider delivery status, separate from send acceptance."}}}}}}