物理明細を追加
const url = 'https://game.retrogather.com/rest/v1/addPhysicalCopy';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"gameId":1,"mode":"materialize","quantity":1,"buyDate":"2026-04-15","buyPrice":1,"buyPlace":"example","rating":1,"memo":"example","attributes":["example"],"editionRef":{"kind":"base"},"makeActive":true,"revision":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://game.retrogather.com/rest/v1/addPhysicalCopy \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "gameId": 1, "mode": "materialize", "quantity": 1, "buyDate": "2026-04-15", "buyPrice": 1, "buyPlace": "example", "rating": 1, "memo": "example", "attributes": [ "example" ], "editionRef": { "kind": "base" }, "makeActive": true, "revision": "example" }'PREMIUM. Physical copies / 所有ソフト追加: library entry required (use addToLibrary if missing). Choose mode by intent: materialize = record details of the copy the user already owns (only when no copies exist; inherits library fields). additional = the user got another copy; when no copies exist it creates TWO rows atomically (the inherited original + the new one). quantity defaults to 1. makeActive:true makes the new copy the representative and overwrites the library’s purchase data, rating, memo and attributes; tell the user. Pass revision from getPhysicalCopies or from the previous successful add/update/remove. Do not send that revision to removePhysicalCopy; start a remove preview instead. Re-read after uncertain results; do not blindly retry.
Plans: PREMIUM. Scopes: library:write.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Materialize: record the already-owned copy from library values (only when no copies exist). additional: add another purchased copy; when no copies exist it creates TWO rows (the inherited original plus the new one). Never inferred from row count.
YYYY-MM-DD. null clears.
Price in JPY. null clears.
1 (lowest) to 5 (highest). null clears.
Attribute IDs or exact labels from listAttributes. Replaces the whole set; [] clears.
True selects this copy as representative and mirrors its purchase data, rating, memo, attributes and images to the library. false/omitted keeps the representative; it never deactivates a copy.
Opaque whole-game revision. Required for add and makeActive:true. After a successful add, update, or remove, reuse that response’s revision for the next physical-copy write. Call getPhysicalCopies when you do not yet have a revision, after revision_conflict, after unavailable/saved:true/lost responses, or when another client may have changed the copies.
Responses
Section titled “ Responses ”Tool result JSON (no MCP envelope). Delete previews also return 200 with confirmToken.
object
object
object
object
object
object
Example
{ "item": { "editionRef": { "kind": "base" } }}Invalid_input (arguments, broken JSON body)
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Missing or invalid API key
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Insufficient_scope, plan_required, or access_suspended
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Target or tool not found
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Already_exists or revision_conflict (stale revision: re-read, then retry)
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Burst or daily quota exceeded. See resetAt.
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Headers
Section titled “Headers”Seconds
Unexpected server failure. Retrying the same call will not help.
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Temporary failure or maintenance. Retry after Retry-After.
Entry errors (auth, routing, quota) use error; tool errors use code and message. Check retryable when present.
object
Examplegenerated
{ "error": "example", "code": "example", "message": "example", "retryable": true, "retryAfterSec": 1, "requestId": "example", "resetAt": "example", "remaining": 1, "scopes": [ "example" ], "upgradeUrl": "example"}Headers
Section titled “Headers”Seconds