{"openapi":"3.1.0","info":{"title":"Mayavoo creator API","version":"1.0.0","description":"Create and maintain your own games with a personal API key. Create keys in /account/api-keys. Read and write keys include read access. Metadata edits affect the live listing; builds require review. JSON request limit: 64 KiB. Upload bytes directly to the signed PUT URL without your API key. See /developers and /developers/creator-api.md for the full workflow."},"servers":[{"url":"/api/v1"}],"externalDocs":{"url":"https://mayavoo.com/developers/creator-api.md","description":"Examples, upload workflow, response fields, errors, and rate limits"},"x-rate-limits":{"periodSeconds":60,"perCloudflareLocation":true,"approximate":true,"requestsPerKey":60,"writesPerKey":10,"requestsPerAccount":120,"writesPerAccount":20,"requestsPerIp":300},"security":[{"creatorKey":[]}],"paths":{"/games":{"get":{"operationId":"listGames","summary":"List your games and account quota","x-required-permission":"games:read","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":300},"description":"Opaque nextCursor from the preceding page."}],"responses":{"200":{"description":"List your games and account quota","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GamePage"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createGame","summary":"Create a draft game","description":"Title is required. Supply other listing text now or later. The response lists missing fields. This consumes a game slot and does not publish the game.","x-required-permission":"games:write","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid"},"description":"Generate and persist one UUID per mutation. Reuse the same UUID and input on retries, within seven days."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGame"}}}},"responses":{"201":{"description":"Create a draft game","headers":{"X-Request-Id":{"schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when returning a previously committed result."},"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedGame"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{gameId}":{"parameters":[{"in":"path","name":"gameId","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getGame","summary":"Read your game's listing and build status","x-required-permission":"games:read","parameters":[],"responses":{"200":{"description":"Read your game's listing and build status","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameDetails"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateGame","summary":"Edit your game's listing","description":"Omitted fields stay unchanged. Arrays replace the entire array. cover:null and screenshots:[] clear images only while the listing can remain incomplete. Submitted and published listings must remain complete. Live listing changes take effect immediately; refreshPending means cache refresh will be retried. Returned media keys are retained copies, suitable for later edits.","x-required-permission":"games:write","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid"},"description":"Generate and persist one UUID per mutation. Reuse the same UUID and input on retries, within seven days."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchGame"}}}},"responses":{"200":{"description":"Edit your game's listing","headers":{"X-Request-Id":{"schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when returning a previously committed result."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatedGame"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{gameId}/uploads":{"parameters":[{"in":"path","name":"gameId","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"reserveUpload","summary":"Reserve a file upload","description":"PUT the raw bytes to url using the returned headers, without Authorization. URLs expire in five minutes. Repeat this reservation with the same Idempotency-Key for a fresh URL to the same object. Reservations expire after seven days. Build ZIP: 50 MiB; JPEG, PNG, WebP image: 5 MiB and 20 million decoded pixels. Thirty new reservations per account per hour.","x-required-permission":"games:write","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid"},"description":"Generate and persist one UUID per mutation. Reuse the same UUID and input on retries, within seven days."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadInput"}}}},"responses":{"201":{"description":"Reserve a file upload","headers":{"X-Request-Id":{"schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when returning a previously committed result."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upload"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{gameId}/versions":{"parameters":[{"in":"path","name":"gameId","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listVersions","summary":"List your game's submitted builds","x-required-permission":"games:read","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":300},"description":"Opaque nextCursor from the preceding page."}],"responses":{"200":{"description":"List your game's submitted builds","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionPage"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"submitVersion","summary":"Submit a build for processing and review","description":"Requires a complete listing and an uploaded buildKey belonging to this game. One pending build per game, five per account. Acceptance does not mean publication. Poll statusUrl at intervals of at least 30 seconds. Replays return the original queued acceptance; GET the version for its current state.","x-required-permission":"games:write","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","format":"uuid"},"description":"Generate and persist one UUID per mutation. Reuse the same UUID and input on retries, within seven days."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"responses":{"202":{"description":"Submit a build for processing and review","headers":{"X-Request-Id":{"schema":{"type":"string"}},"Idempotency-Replayed":{"schema":{"type":"boolean"},"description":"True when returning a previously committed result."},"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"},"description":"Poll after at least 30 seconds."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmittedVersion"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/games/{gameId}/versions/{versionId}":{"parameters":[{"in":"path","name":"gameId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"versionId","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getVersion","summary":"Read processing and review status","x-required-permission":"games:read","parameters":[],"responses":{"200":{"description":"Read processing and review status","headers":{"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionDetails"}}}},"default":{"description":"Request failed. Inspect error.code, error.fields, error.retryable and Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Minimum wait in seconds when throttled."},"X-Request-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"creatorKey":{"type":"http","scheme":"bearer","bearerFormat":"mayavoo_...","description":"Personal API key, shown once, expires in 90 days. Use HTTPS. Never place it in URLs or browser/game code."}},"schemas":{"CreateGame":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"shortDescription":{"type":"string","maxLength":240},"description":{"type":"string","maxLength":10000},"instructions":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":50},"devices":{"maxItems":3,"type":"array","items":{"type":"string","enum":["desktop","mobile","tablet"]}},"orientation":{"type":"string","enum":["any","landscape","portrait"]},"contentNotes":{"type":"string","maxLength":2000}},"required":["title"],"additionalProperties":false},"PatchGame":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"shortDescription":{"type":"string","maxLength":240},"description":{"type":"string","maxLength":10000},"instructions":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":50},"devices":{"maxItems":3,"type":"array","items":{"type":"string","enum":["desktop","mobile","tablet"]}},"orientation":{"type":"string","enum":["any","landscape","portrait"]},"contentNotes":{"type":"string","maxLength":2000},"cover":{"anyOf":[{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._/-]*$"},"alt":{"default":"","type":"string","maxLength":300}},"required":["key"],"additionalProperties":false},{"type":"null"}]},"screenshots":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._/-]*$"},"alt":{"default":"","type":"string","maxLength":300}},"required":["key"],"additionalProperties":false}}},"additionalProperties":false,"minProperties":1},"Release":{"type":"object","properties":{"buildKey":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._/-]*$"}},"required":["buildKey"],"additionalProperties":false},"UploadInput":{"type":"object","properties":{"kind":{"type":"string","enum":["build","cover","screenshot"]},"size":{"type":"integer","exclusiveMinimum":0,"maximum":52428800},"contentType":{"type":"string","enum":["application/zip","image/jpeg","image/png","image/webp"]}},"required":["kind","size","contentType"],"additionalProperties":false,"oneOf":[{"properties":{"kind":{"const":"build"},"contentType":{"const":"application/zip"},"size":{"maximum":52428800}}},{"properties":{"kind":{"enum":["cover","screenshot"]},"contentType":{"enum":["image/jpeg","image/png","image/webp"]},"size":{"maximum":5242880}}}]},"Listing":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"shortDescription":{"type":"string","maxLength":240},"description":{"type":"string","maxLength":10000},"instructions":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":50},"devices":{"maxItems":3,"type":"array","items":{"type":"string","enum":["desktop","mobile","tablet"]}},"orientation":{"type":"string","enum":["any","landscape","portrait"]},"contentNotes":{"type":"string","maxLength":2000},"cover":{"anyOf":[{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._/-]*$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":20000000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":20000000},"alt":{"type":"string","maxLength":300}},"required":["key","width","height","alt"],"additionalProperties":false},{"type":"null"}]},"screenshots":{"maxItems":6,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":512,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9._/-]*$"},"width":{"type":"integer","exclusiveMinimum":0,"maximum":20000000},"height":{"type":"integer","exclusiveMinimum":0,"maximum":20000000},"alt":{"type":"string","maxLength":300}},"required":["key","width","height","alt"],"additionalProperties":false}}},"required":["title","shortDescription","description","instructions","category","devices","orientation","contentNotes","cover","screenshots"],"additionalProperties":false},"CreatedGame":{"type":"object","properties":{"game":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"}},"required":["id","slug"],"additionalProperties":false},"listing":{"$ref":"#/components/schemas/Listing"},"missingFields":{"type":"array","items":{"type":"string"}},"quota":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"}},"required":["used","limit"],"additionalProperties":false}},"required":["game","listing","missingFields","quota"],"additionalProperties":false},"UpdatedGame":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/Listing"},"live":{"type":"boolean"},"missingFields":{"type":"array","items":{"type":"string"}},"refreshPending":{"type":"boolean"}},"required":["listing","live","missingFields","refreshPending"],"additionalProperties":false},"GameDetails":{"type":"object","properties":{"game":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"disabled":{"type":"boolean"},"publishedVersionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","slug","disabled","publishedVersionId"],"additionalProperties":false},"listing":{"$ref":"#/components/schemas/Listing"},"latestVersion":{"anyOf":[{"$ref":"#/components/schemas/Version"},{"type":"null"}]},"publishedVersion":{"anyOf":[{"$ref":"#/components/schemas/Version"},{"type":"null"}]},"missingFields":{"type":"array","items":{"type":"string"}},"refreshPending":{"type":"boolean"}},"required":["game","listing","latestVersion","publishedVersion","missingFields","refreshPending"],"additionalProperties":false},"GamePage":{"type":"object","properties":{"games":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"shortDescription":{"type":"string"},"disabled":{"type":"boolean"},"publishedVersionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"latestVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"status":{"anyOf":[{"type":"string","enum":["queued","processing","in_review","approved","rejected","failed"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","slug","title","shortDescription","disabled","publishedVersionId","latestVersion","status","createdAt"],"additionalProperties":false}},"quota":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"}},"required":["used","limit"],"additionalProperties":false},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["games","quota","nextCursor"],"additionalProperties":false},"Version":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"versionNumber":{"type":"integer"},"status":{"type":"string","enum":["queued","processing","in_review","approved","rejected","failed"]},"submittedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"failureCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"rejectionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"isLive":{"type":"boolean"}},"required":["id","versionNumber","status","submittedAt","failureCode","rejectionReason","isLive"],"additionalProperties":false},"VersionPage":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/Version"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["versions","nextCursor"],"additionalProperties":false},"VersionDetails":{"type":"object","properties":{"version":{"$ref":"#/components/schemas/Version"}},"required":["version"],"additionalProperties":false},"SubmittedVersion":{"type":"object","properties":{"versionId":{"type":"string","format":"uuid"},"versionNumber":{"type":"integer"},"status":{"const":"queued"},"statusUrl":{"type":"string"}},"required":["versionId","versionNumber","status","statusUrl"],"additionalProperties":false},"Upload":{"type":"object","properties":{"key":{"type":"string"},"url":{"type":"string","format":"uri"},"method":{"const":"PUT"},"headers":{"type":"object","properties":{"Content-Type":{"type":"string"},"Content-Length":{"type":"string"}},"required":["Content-Type","Content-Length"],"additionalProperties":false},"expiresIn":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"}},"required":["key","url","method","headers","expiresIn","expiresAt"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}},"retryable":{"type":"boolean"}},"required":["code","message","fields","retryable"],"additionalProperties":false},"requestId":{"type":"string","format":"uuid"}},"required":["error","requestId"],"additionalProperties":false}}}}