{ "openapi": "3.1.0", "info": { "title": "MyStoryInABook Agent Service", "version": "1.1.0", "description": "Default-off, owner-authorized task API for all eight active product adapters. Relative paths share the backend origin with the application's /v1 routes. Hosted checkout remains owner-action; no A2A, ACP, AP2, autonomous card charges, account creation/deletion, publication, or physical shipping is implemented." }, "servers": [ { "url": "/" } ], "paths": { "/v1/agent/catalog": { "get": { "operationId": "getAgentCatalog", "summary": "Read product schemas and current execution state", "responses": { "200": { "description": "Catalog, versioned input schemas, and feature state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "service", "version", "mutations_enabled", "products", "auth" ], "properties": { "service": { "type": "string" }, "version": { "type": "string" }, "mutations_enabled": { "type": "boolean" }, "products": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "execution_enabled", "schema" ], "properties": { "id": { "type": "string", "enum": [ "children_books", "story_universe", "learner_editions", "haunted_tales", "story_from_photo", "audio_comics", "manuscript_critique", "adventures" ] }, "name": { "type": "string" }, "execution_enabled": { "type": "boolean" }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/ChildrenBooksSchemaDescriptor" }, { "$ref": "#/components/schemas/StoryUniverseSchemaDescriptor" }, { "$ref": "#/components/schemas/LearnerEditionsSchemaDescriptor" }, { "$ref": "#/components/schemas/HauntedTalesSchemaDescriptor" }, { "$ref": "#/components/schemas/StoryFromPhotoSchemaDescriptor" }, { "$ref": "#/components/schemas/ComicSchemaDescriptor" }, { "$ref": "#/components/schemas/ManuscriptCritiqueSchemaDescriptor" }, { "$ref": "#/components/schemas/BedtimeAdventuresSchemaDescriptor" }, { "type": "null" } ] } } } }, "auth": { "type": "object", "properties": { "grant_header": { "type": "string" }, "idempotency_header": { "type": "string" } } } } } } } } } } }, "/v1/agent/sources": { "get": { "operationId": "listAgentSources", "summary": "List eligible source publications for Learner Editions", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "const": "learner_editions" } } ], "responses": { "200": { "description": "Currently eligible public source summaries." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/grants": { "post": { "operationId": "createAgentGrant", "summary": "Create a scoped grant (owner access token required)", "security": [ { "OwnerBearer": [ ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRequest" } } } }, "responses": { "201": { "description": "Grant created; grant_token is returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/grants/{grant_id}": { "delete": { "operationId": "revokeAgentGrantById", "summary": "Revoke an owner-issued grant", "security": [ { "OwnerBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/GrantId" } ], "responses": { "200": { "description": "Grant revoked; future agent requests with the token fail. An already prepared standard hosted checkout remains an owner-authorized checkout unless the owner calls POST /v1/orders/{order_id}/checkout-cancel while it is pending. Revocation does not silently cancel Stripe sessions or refund a completed payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_id", "revoked" ], "properties": { "grant_id": { "type": "string" }, "revoked": { "const": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/tasks": { "post": { "operationId": "createAgentTask", "summary": "Create an owner-bound task for any enabled product adapter", "description": "Requires an Idempotency-Key and product-specific create scope. Some products prepare checkout as part of task creation; Books, photo products, and Comic first return a task requiring a separate checkout action. Child, photo, publication-rights, and comic attestations are required as applicable.", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/TaskResponse" }, "200": { "$ref": "#/components/responses/TaskResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/tasks/{task_id}": { "get": { "operationId": "getAgentTask", "summary": "Read task state and owner-action instructions", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "$ref": "#/components/responses/TaskResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/tasks/{task_id}/checkout": { "post": { "operationId": "prepareAgentTaskCheckout", "summary": "Prepare normal owner-action checkout for a task", "description": "Used after initial task setup for Children's Books, Haunted Tales, Story from Photo, and Comic. Accepts only an optional voucher_code. Story Universe, Learner Editions, Manuscript Critique, and Bedtime Adventures prepare checkout during task creation.", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/TaskId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/TaskResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/tasks/{task_id}/source": { "post": { "operationId": "uploadAgentProductSource", "summary": "Upload a rights-confirmed image for a photo or Comic task", "description": "Provide a multipart file and an input form field containing the JSON object {}. Product rights and image-safety fields were recorded at task creation. The original Comic upload is not retained by the analysis workflow.", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/TaskId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "input" ], "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG, PNG, or WebP image within the configured upload limit." }, "input": { "type": "string", "const": "{}", "description": "JSON form field; currently the empty object." } } } } } }, "responses": { "202": { "$ref": "#/components/responses/TaskResponse" }, "200": { "$ref": "#/components/responses/TaskResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/tasks/{task_id}/manuscript": { "post": { "operationId": "uploadCritiqueManuscript", "summary": "Upload a rights-confirmed manuscript to a paid critique task", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/TaskId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "rights_confirmed" ], "properties": { "file": { "type": "string", "format": "binary", "description": ".md, .txt, .docx, .pdf, or .epub; maximum 1.5 MB." }, "rights_confirmed": { "type": "boolean", "const": true } } } } } }, "responses": { "202": { "$ref": "#/components/responses/TaskResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Owner checkout is not yet paid." }, "409": { "$ref": "#/components/responses/Conflict" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/tasks/{task_id}/artifacts": { "get": { "operationId": "listAgentTaskArtifacts", "summary": "List allowlisted native files for a completed task", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "Empty until the task and promised artifact manifest are complete.", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "artifacts" ], "properties": { "task_id": { "type": "string" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agent/tasks/{task_id}/artifacts/{artifact_id}": { "get": { "operationId": "downloadAgentTaskArtifact", "summary": "Download one owner-authorized native artifact", "security": [ { "AgentBearer": [ ] } ], "parameters": [ { "$ref": "#/components/parameters/TaskId" }, { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Native artifact bytes; response includes X-Asset-SHA256.", "content": { "text/markdown": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "OwnerBearer": { "type": "http", "scheme": "bearer", "description": "Existing owner access token; explicit header required for grant lifecycle." }, "AgentBearer": { "type": "http", "scheme": "bearer", "description": "Owner-issued scoped grant token, accepted only on /v1/agent routes." } }, "parameters": { "GrantId": { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string" } }, "TaskId": { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" } } }, "responses": { "BadRequest": { "description": "Invalid schema, unsupported product, disabled feature, or request input." }, "Unauthorized": { "description": "Missing or invalid owner/grant bearer token." }, "NotFound": { "description": "Feature disabled or task/artifact is not visible to this grant." }, "Conflict": { "description": "Idempotency key was reused with a different request payload." }, "TaskResponse": { "description": "Allowlisted task status; no provider diagnostics or internal paths.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } } }, "schemas": { "GrantRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "children_books:create", "story_universe:create", "learner_editions:create", "haunted_tales:create", "story_from_photo:create", "audio_comics:create", "manuscript_critique:create", "adventures:create", "assets:read" ] } }, "owner_authorizations": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "children_books:child_data_authority_v1", "learner_editions:source_transformation_v1", "haunted_tales:photo_rights_v1", "story_from_photo:photo_rights_v1", "audio_comics:comic_upload_rights_v1", "adventures:child_data_authority_v1" ] } }, "max_purchase_value_cents": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Positive when a create scope is granted; zero for read-only grants." }, "max_purchases": { "type": "integer", "minimum": 0, "maximum": 20, "description": "Number of reserved task slots; creation grants require at least one." }, "expires_in_seconds": { "type": "integer", "minimum": 3600, "maximum": 7776000, "default": 2592000 } } }, "GrantCreated": { "type": "object", "required": [ "grant_id", "name", "scopes", "currency", "max_purchase_value_cents", "max_purchases", "expires_at", "grant_token" ], "properties": { "grant_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "owner_authorizations": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "string" }, "max_purchase_value_cents": { "type": "integer" }, "max_purchases": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "grant_token": { "type": "string", "description": "High-entropy token shown only at creation; store securely." }, "token_display": { "type": "string" } } }, "TaskCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "product_id", "input" ], "properties": { "product_id": { "type": "string", "enum": [ "children_books", "story_universe", "learner_editions", "haunted_tales", "story_from_photo", "audio_comics", "manuscript_critique", "adventures" ] }, "input": { "oneOf": [ { "$ref": "#/components/schemas/ChildrenBooksInput" }, { "$ref": "#/components/schemas/StoryUniverseInput" }, { "$ref": "#/components/schemas/LearnerEditionsInput" }, { "$ref": "#/components/schemas/HauntedTalesInput" }, { "$ref": "#/components/schemas/StoryFromPhotoInput" }, { "$ref": "#/components/schemas/ComicInput" }, { "$ref": "#/components/schemas/ManuscriptCritiqueInput" }, { "$ref": "#/components/schemas/BedtimeAdventuresInput" } ] } } }, "CheckoutRequest": { "type": "object", "additionalProperties": false, "properties": { "voucher_code": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "ChildrenBooksInput": { "type": "object", "additionalProperties": false, "required": [ "title", "name", "character_description", "story_hint" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "character_description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "story_hint": { "type": "string", "minLength": 1, "maxLength": 2000 }, "dedication": { "type": "string", "maxLength": 500 }, "language": { "type": "string", "enum": [ "en", "de", "es", "fr", "it", "nl", "pt", "ru", "uk" ] } } }, "StoryUniverseInput": { "type": "object", "additionalProperties": false, "required": [ "title", "premise" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "premise": { "type": "string", "minLength": 1, "maxLength": 3900 }, "include_image": { "type": "boolean" }, "genre": { "type": "string", "maxLength": 255 }, "tone": { "type": "string", "maxLength": 255 }, "target_audience": { "type": "string", "maxLength": 255 }, "length_preset": { "type": "string", "enum": [ "micro_story", "short_story", "long_short_story", "custom" ] }, "target_length_words": { "type": "integer", "minimum": 50, "maximum": 20000 }, "language_code": { "type": "string", "enum": [ "en", "de", "es", "fr", "it", "nl", "pt", "ru", "uk" ] }, "voucher_code": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "LearnerEditionsInput": { "type": "object", "additionalProperties": false, "required": [ "publication_ids", "target_language", "cefr" ], "properties": { "publication_ids": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "target_language": { "type": "string", "enum": [ "en", "de", "es", "fr", "it", "nl", "pt", "ru", "uk" ] }, "cefr": { "type": "string", "enum": [ "A1", "A2", "B1", "B2", "C1", "C2", "C2+" ] }, "lookahead": { "type": "integer", "minimum": 1, "maximum": 5 }, "voucher_code": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "HauntedTalesInput": { "type": "object", "additionalProperties": false, "required": [ "no_people_confirmed", "adult_acknowledged" ], "properties": { "no_people_confirmed": { "type": "boolean", "const": true }, "adult_acknowledged": { "type": "boolean", "const": true }, "language": { "type": "string", "enum": [ "en", "de", "es", "it", "nl", "pt", "ru", "uk" ] }, "title": { "type": "string", "maxLength": 120 }, "mode": { "type": "string", "enum": [ "ghost", "suspense", "child_safe_spooky" ] }, "target_words": { "type": "integer", "enum": [ 300, 400, 500 ] }, "coarse_place": { "type": "string", "maxLength": 255 } } }, "StoryFromPhotoInput": { "type": "object", "additionalProperties": false, "required": [ "no_people_confirmed", "adult_acknowledged" ], "properties": { "no_people_confirmed": { "type": "boolean", "const": true }, "adult_acknowledged": { "type": "boolean", "const": true }, "language": { "type": "string", "enum": [ "en", "de", "es", "it", "nl", "pt", "ru", "uk" ] }, "title": { "type": "string", "maxLength": 120 }, "mode": { "type": "string", "enum": [ "romance", "mystery", "fantasy", "adventure", "childrens" ] }, "target_words": { "type": "integer", "enum": [ 300, 400, 500 ] }, "coarse_place": { "type": "string", "maxLength": 255 } } }, "ComicInput": { "type": "object", "additionalProperties": false, "required": [ "rights_attestation_version", "authority_confirmed" ], "properties": { "rights_attestation_version": { "type": "string", "const": "comic_upload_rights_v1" }, "authority_confirmed": { "type": "boolean", "const": true }, "language": { "type": "string", "enum": [ "en", "de", "es", "fr", "it", "nl", "pt", "ru", "uk" ] }, "title": { "type": "string", "maxLength": 120 }, "story_idea": { "type": "string", "maxLength": 600 }, "genre": { "type": "string", "enum": [ "adventure", "fantasy", "mystery", "comedy", "science_fiction", "everyday_magic" ] }, "style": { "type": "string", "enum": [ "bright_adventure", "gentle_watercolor", "bold_graphic", "cozy_classic" ] }, "perspective": { "type": "string", "enum": [ "first_person", "second_person", "observer" ] }, "ending": { "type": "string", "enum": [ "hopeful", "clever_reveal", "warm_resolution" ] } } }, "ManuscriptCritiqueInput": { "type": "object", "additionalProperties": false, "required": [ "plan", "title", "filename" ], "properties": { "plan": { "type": "string", "enum": [ "small", "book" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "filename": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Must end in .md, .txt, .docx, .pdf, or .epub." }, "genre": { "type": "string", "maxLength": 255 }, "voucher_code": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "BedtimeAdventuresInput": { "type": "object", "additionalProperties": false, "required": [ "child_name", "age_range", "series_brief" ], "properties": { "child_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "age_range": { "type": "string", "enum": [ "Ages 3–5", "Ages 5–8", "Ages 9–11" ] }, "series_brief": { "type": "string", "minLength": 1, "maxLength": 2000 }, "interests": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "avoid_text": { "type": "string", "maxLength": 240 }, "language_code": { "type": "string", "enum": [ "en", "de", "es", "fr", "it", "nl", "pt", "ru", "uk" ] }, "series_direction": { "type": "string", "maxLength": 240 }, "voucher_code": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "ChildrenBooksSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/ChildrenBooksInput" } } }, "StoryUniverseSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/StoryUniverseInput" } } }, "LearnerEditionsSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/LearnerEditionsInput" } } }, "HauntedTalesSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/HauntedTalesInput" } } }, "StoryFromPhotoSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/StoryFromPhotoInput" } } }, "ComicSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/ComicInput" } } }, "ManuscriptCritiqueSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/ManuscriptCritiqueInput" } } }, "BedtimeAdventuresSchemaDescriptor": { "type": "object", "required": [ "schema_version", "schema" ], "properties": { "schema_version": { "const": "1.0" }, "schema": { "$ref": "#/components/schemas/BedtimeAdventuresInput" } } }, "Task": { "type": "object", "required": [ "task_id", "product_id", "status", "currency", "authorized_value_cents" ], "properties": { "task_id": { "type": "string" }, "product_id": { "type": "string" }, "status": { "type": "string", "enum": [ "checkout_preparing", "awaiting_checkout", "awaiting_source_upload", "analysis_queued", "analysis_running", "awaiting_payment", "awaiting_manuscript", "processing", "fulfillment_queued", "profile_running", "reconciliation_required", "complete", "failed" ] }, "currency": { "type": "string" }, "authorized_value_cents": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "payment": { "type": "object", "properties": { "owner_action_required": { "type": "boolean" }, "checkout_url": { "type": [ "string", "null" ], "format": "uri" } } }, "next_action": { "type": "string" }, "artifacts_url": { "type": "string" }, "recovery": { "type": "object", "properties": { "required": { "type": "boolean" }, "automatic": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "provider_outcome_uncertain" ] } } }, "failure": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } } } } }, "Artifact": { "type": "object", "required": [ "artifact_id", "type", "format", "size_bytes", "sha256", "download_url" ], "properties": { "artifact_id": { "type": "string" }, "type": { "type": "string" }, "format": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 1 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "download_url": { "type": "string" } } } } } }