InstaMapp API · v1

Build on your collection data

The InstaMapp REST API lets Business-tier teams read and manage their inventory, collections, listings, and sales programmatically. Predictable resource-oriented URLs, JSON everywhere, API-key authentication, and scoped access.

Authentication

Authenticate every request with an API key in the Authorization header as a bearer token. Create and manage keys in your Business team settings — the full key is shown once, so store it somewhere safe.

curl /api/public/v1/items \
  -H "Authorization: Bearer imk_live_your_key_here"

Keys are scoped — each key only works for the scopes you grant it (e.g. items:read). Keep keys server-side; never expose them in a browser or mobile app.

Quickstart

1. Open your Business team settings → API keys.
2. Create a key, choose its scopes, and copy the secret (shown once).
3. Call the API with the key in the Authorization header.

const res = await fetch("/api/public/v1/items?per_page=10", {
  headers: { Authorization: `Bearer ${process.env.INSTAMAPP_API_KEY}` },
});
const { data, pagination } = await res.json();
console.log(data.length, "items; more?", pagination.has_more);

Run these examples from a server or trusted backend job. Do not ship API keys in browser code.

import os, requests

r = requests.get(
    "/api/public/v1/items",
    headers={"Authorization": f"Bearer {os.environ['INSTAMAPP_API_KEY']}"},
    params={"per_page": 10},
)
r.raise_for_status()
print(r.json()["data"])

Rate limits

Requests are limited per API key. When you exceed the limit you get a 429 response; check the standard RateLimit-* response headers to pace your requests. Every response also includes an X-Request-Id for support.

Errors

Errors use a consistent envelope and conventional HTTP status codes.

{
  "error": {
    "type": "not_found",
    "message": "No item with that id."
  }
}

Pagination

List endpoints accept page (1-based) and per_page (1–100, default 20), and return a pagination object with has_more.

{
  "object": "list",
  "data": [ /* … */ ],
  "pagination": { "page": 1, "per_page": 20, "has_more": true }
}

Items

curl "/api/public/v1/items?status=sell&per_page=20" \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY"

curl /api/public/v1/items/itm_123 \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY"

curl -X POST /api/public/v1/items \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "00000000-0000-0000-0000-000000000000",
    "name": "Custom Otto",
    "status": "keep",
    "condition": "loose_mint",
    "estimated_value": 24.99
  }'

curl -X PATCH /api/public/v1/items/itm_123 \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "sell", "estimated_value": 30 }'

Collections

curl /api/public/v1/collections \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY"

Marketplace

curl /api/public/v1/marketplace/listings \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY"

Sales

curl /api/public/v1/sales/summary \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY"