InstaMapp API · v1

Build on your collection data

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

API key management

Enterprise workspace owners and admins can create, scope, review, and revoke keys in workspace settings. Use one key per integration so access can be rotated without interrupting other systems.

• Grant only the scopes the integration needs.
• Store keys in a server-side secret manager, never source control or browser code.
• Revoke a key immediately when an integration or operator no longer needs access.

Authentication

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

curl https://instamapp.com/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 Enterprise 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("https://instamapp.com/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(
    "https://instamapp.com/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"])

Versioning

The major API version is part of every URL: /api/public/v1. Additive fields may appear within v1, so clients should ignore unknown response properties. Breaking request or response changes ship under a new major path with migration guidance.

Webhooks

Customer-configurable webhooks are not generally available yet. Integrations should poll the relevant list endpoints using stable resource IDs and conservative intervals. Webhook signing, retries, event versioning, and replay guidance will be published here before webhook access is enabled.

Request IDs

Every API response includes X-Request-Id. Record it with your logs and include it when contacting support so InstaMapp can trace the request without receiving your API key or customer payload.

curl -sS -D - https://instamapp.com/api/public/v1/items \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY" \
  -o /dev/null | grep -i x-request-id

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 "https://instamapp.com/api/public/v1/items?status=sell&per_page=20" \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY"

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

curl -X POST https://instamapp.com/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 https://instamapp.com/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 https://instamapp.com/api/public/v1/collections \
  -H "Authorization: Bearer $INSTAMAPP_API_KEY"

Marketplace

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

Sales

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