{"openapi":"3.1.0","info":{"title":"InstaMapp Public API","version":"2026-06-01","description":"The InstaMapp public API lets Business-tier customers read and manage their collection, listings, and sales programmatically. All endpoints are authenticated with an API key and scoped to the key's team.","contact":{"name":"InstaMapp Support","url":"https://instamapp.app/developers"}},"servers":[{"url":"/api/public/v1","description":"Public API v1"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Items","description":"Collectible items in your inventory."},{"name":"Collections","description":"Groupings of items."},{"name":"Marketplace","description":"Your active listings."},{"name":"Sales","description":"Earnings and fee reporting."}],"paths":{"/items":{"get":{"tags":["Items"],"summary":"List items","description":"Returns a paginated list of items in your team, newest first.","operationId":"listItems","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["items:read"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"status","in":"query","required":false,"description":"Filter by item status.","schema":{"type":"string","enum":["keep","sell","trade","sold","archived"]}}],"responses":{"200":{"description":"A list of items.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["object","data","pagination"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Items"],"summary":"Create an item","description":"Adds an item to one of your collections. Counts against your plan's item limit.","operationId":"createItem","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["items:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemCreate"}}}},"responses":{"201":{"description":"The created item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/items/{id}":{"get":{"tags":["Items"],"summary":"Retrieve an item","operationId":"getItem","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["items:read"],"parameters":[{"$ref":"#/components/parameters/IdPath"}],"responses":{"200":{"description":"The item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Items"],"summary":"Update an item","description":"Partially updates an item. Only the fields you send are changed.","operationId":"updateItem","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["items:write"],"parameters":[{"$ref":"#/components/parameters/IdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemUpdate"}}}},"responses":{"200":{"description":"The updated item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/collections":{"get":{"tags":["Collections"],"summary":"List collections","operationId":"listCollections","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["collections:read"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"A list of collections.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["object","data","pagination"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/marketplace/listings":{"get":{"tags":["Marketplace"],"summary":"List your active listings","description":"Items in your team currently for sale or trade.","operationId":"listListings","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["marketplace:read"],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"A list of listed items.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["object","data","pagination"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sales/summary":{"get":{"tags":["Sales"],"summary":"Sales & earnings summary","operationId":"getSalesSummary","security":[{"ApiKeyAuth":[]}],"x-required-scopes":["analytics:read"],"responses":{"200":{"description":"Aggregated sales totals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Pass your API key as `Authorization: Bearer imk_live_…`. Create keys in your Business team settings."}},"parameters":{"Page":{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","required":false,"description":"Results per page (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"IdPath":{"name":"id","in":"path","required":true,"description":"Resource id (UUID).","schema":{"type":"string","format":"uuid"}}},"schemas":{"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"has_more":{"type":"boolean"}},"required":["page","per_page","has_more"]},"Item":{"type":"object","properties":{"object":{"type":"string","enum":["item"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"brand":{"type":["string","null"]},"series":{"type":["string","null"]},"release_year":{"type":["integer","null"]},"condition":{"type":["string","null"]},"packaging":{"type":["string","null"]},"status":{"type":"string","enum":["keep","sell","trade","sold","archived"]},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object","additionalProperties":true},"collection_id":{"type":"string","format":"uuid"},"estimated_value":{"type":["number","null"],"description":"Latest estimated value in the listed currency."},"currency":{"type":"string","example":"usd"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","status","collection_id","currency","created_at","updated_at"]},"ItemCreate":{"type":"object","description":"Fields accepted when creating an item.","properties":{"collection_id":{"type":"string","format":"uuid","description":"A collection in your team."},"name":{"type":"string","minLength":1,"maxLength":255},"brand":{"type":["string","null"]},"series":{"type":["string","null"]},"release_year":{"type":["integer","null"],"minimum":1968,"maximum":2100},"condition":{"type":["string","null"],"enum":["mint_on_card","loose_mint","loose_good","loose_fair","damaged",null]},"packaging":{"type":["string","null"],"enum":["in_package","opened","loose","custom",null]},"status":{"type":"string","enum":["keep","sell","trade","sold","archived"],"default":"keep"},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object","additionalProperties":true},"estimated_value":{"type":["number","null"],"minimum":0}},"required":["collection_id","name"],"additionalProperties":false},"ItemUpdate":{"type":"object","description":"Partial update — send only the fields you want to change (at least one).","minProperties":1,"properties":{"collection_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"brand":{"type":["string","null"]},"series":{"type":["string","null"]},"release_year":{"type":["integer","null"],"minimum":1968,"maximum":2100},"condition":{"type":["string","null"],"enum":["mint_on_card","loose_mint","loose_good","loose_fair","damaged",null]},"packaging":{"type":["string","null"],"enum":["in_package","opened","loose","custom",null]},"status":{"type":"string","enum":["keep","sell","trade","sold","archived"]},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object","additionalProperties":true},"estimated_value":{"type":["number","null"],"minimum":0}},"additionalProperties":false},"Collection":{"type":"object","properties":{"object":{"type":"string","enum":["collection"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"is_public":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","name","is_public","created_at","updated_at"]},"SalesSummary":{"type":"object","properties":{"object":{"type":"string","enum":["sales_summary"]},"completed_count":{"type":"integer"},"gross_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"refunded_cents":{"type":"integer"},"net_payout_cents":{"type":"integer"},"refunded_count":{"type":"integer"},"disputed_count":{"type":"integer"},"pending_count":{"type":"integer"}},"required":["object","completed_count","gross_cents","fee_cents","net_payout_cents"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable error type."},"message":{"type":"string","description":"Human-readable description."}},"required":["type","message"]}},"required":["error"]}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}