Instica API — Overview & Quickstart

Base URL

All API requests are made to the production server. Endpoints are namespaced under /api/ (auth routes) and /api/v1/ (all domain resources). New integrations should target /api/v1/ where available.

All requests and responses use Content-Type: application/json unless otherwise noted (e.g., multipart file uploads).

Base URL

https://app.instica.com

Quickstart — your first API call

Authenticate and fetch your products in three steps.

1. Create an API key

Create an API key from your Account Settings → API Keys page, or programmatically via the API keys endpoint. Store the key securely — it is only shown once at creation time.

API key header

# Include your API key in every request
curl https://app.instica.com/api/v1/products/ \
  -H "X-API-Key: YOUR_API_KEY"

2. List your products

Include the API key in every request via the X-API-Key header. The products endpoint returns a paginated list with nested inventory counts and marketplace data.

Request

curl https://app.instica.com/api/v1/products/ \
  -H "X-API-Key: YOUR_API_KEY"

Response — 200 OK

{
  "count": 247,
  "next": "https://app.instica.com/api/v1/products/?page=2",
  "previous": null,
  "results": [
    {
      "uid": "prod_a1b2c3",
      "title": "Abbey Road",
      "type": "physical",
      "artist": { "uid": "art_x1", "name": "The Beatles" },
      "catalog_number": "PCS 7088",
      "total_inventory_count": 3,
      "listed_inventory_count": 1,
      "available_inventory_count": 2,
      "product_image": "https://cdn.instica.com/..."
    }
  ]
}

3. Get a single inventory item

Use the inventory UID from the product response to fetch the full inventory item detail, including condition grading, pricing, assets, and listing status.

Tip: All resource identifiers use UIDs (e.g., prod_a1b2c3, inv_d4e5f6). Store these as strings — never parse or assume their format.

Request

curl https://app.instica.com/api/v1/inventory/inv_d4e5f6/ \
  -H "X-API-Key: YOUR_API_KEY"

Authentication

All API requests (except registration and health checks) require authentication via the X-API-Key header (recommended) or a bearer token in the Authorization header.

API keys are created and managed through /api/v1/api-keys/ or your account settings. Bearer tokens are obtained via POST /api/auth/apple/ (Apple Sign In) for mobile and web app sessions.

See the Authentication guide for all auth flows including registration, password reset, and social account linking.

Authenticated request

curl https://app.instica.com/api/v1/products/ \
  -H "Authorization: Bearer YOUR_TOKEN"

API key authentication

curl https://app.instica.com/api/v1/products/ \
  -H "X-API-Key: YOUR_API_KEY"

Pagination

All list endpoints return paginated results. Use page and page_size query parameters to control paging.

The response envelope includes:

Field	Type	Description
`count`	integer	Total results across all pages
`next`	string \| null	URL of the next page
`previous`	string \| null	URL of the previous page
`results`	array	Resource objects for the current page

Default page sizes vary by resource: Products = 15, Inventory = 10, Orders = 25. Maximum page size is 100 for all endpoints.

Important: Always set page_size explicitly in your integration. The server defaults differ by endpoint.

Paginated request

curl "https://app.instica.com/api/v1/products/?page=2&page_size=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response envelope

{
  "count": 247,
  "next": "https://app.instica.com/api/v1/products/?page=3&page_size=25",
  "previous": "https://app.instica.com/api/v1/products/?page=1&page_size=25",
  "results": [ ... ]
}

Filtering & ordering

Most list endpoints support full-text search and field ordering via query parameters.

Parameter	Example	Description
`search`	`?search=abbey road`	Full-text search across title, SKU, catalog number, artist, label
`ordering`	`?ordering=-updated`	Sort field. Prefix `-` for descending.
`status`	`?status=listed`	Filter by resource status. Can be comma-separated or repeated.
`has_inventory`	`?has_inventory=true`	Products with/without inventory items
`type`	`?type=physical`	Filter by product type (`physical`, `digital`)
`tags`	`?tags=jazz,vinyl`	Comma-separated, OR logic, case-insensitive

Custom ordering options

In addition to standard field ordering (created, updated, title, price_total_usd), some endpoints support computed orderings:

listed_first / unlisted_first — sort by listing status
price_high_low / price_low_high — sort by price
most_inventory / least_inventory — sort by item count
days_in_inventory — sort by age (inventory only)

Combined filters + search

curl "https://app.instica.com/api/v1/products/?search=beatles&has_inventory=true&ordering=-updated&page_size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Inventory-specific filters

# Filter by multiple statuses
curl "https://app.instica.com/api/v1/inventory/?status=ready-to-sell,listed&ordering=price_total_usd" \
  -H "Authorization: Bearer YOUR_TOKEN"

Error handling

The API uses standard HTTP status codes. Error responses include a JSON body with per-field validation details.

Status	Meaning	What to do
`400`	Bad Request	Check request body — validation errors are returned per-field
`401`	Unauthorized	Token missing, invalid, or invalidated. Re-authenticate.
`402`	Payment Required	Active subscription required for this action
`403`	Forbidden	You don't have permission for this resource
`404`	Not Found	Resource doesn't exist or belongs to another user
`429`	Too Many Requests	Rate limit exceeded. Back off and retry.
`500`	Server Error	Retry with exponential backoff. Contact support if persistent.

Validation error format

Validation errors (400) return a JSON object where keys are field names and values are arrays of error messages. Non-field errors use the key non_field_errors.

Field validation error — 400

{
  "title": [
    "This field may not be blank."
  ],
  "price_total_usd": [
    "Ensure this value is greater than 0."
  ]
}

Authentication error — 401

{
  "detail": "Authentication credentials were not provided."
}

Non-field error — 400

{
  "non_field_errors": [
    "Unable to log in with provided credentials."
  ]
}

Rate limits

The API enforces rate limits to ensure service stability. Specific limits apply to sensitive endpoints:

Endpoint	Limit
Password reset request	3 per user per hour
Email recovery	5 per phone per 15 minutes
General API	Server-enforced per-user throttle

If you receive a 429 Too Many Requests response, wait before retrying. Use exponential backoff with jitter for automated retries.

Authentication methods

Choose the right authentication method for your use case:

Method	Header	Best for	Expiry
API key	`X-API-Key: <key>`	Integrations, scripts, extensions, server-to-server	Until rotated or deleted
Bearer token	`Authorization: Bearer <token>`	Mobile apps, web app sessions (via Apple Sign In)	Persistent until logout

Rate limit response — 429

{
  "detail": "Request was throttled. Expected available in 30 seconds."
}

Bearer token auth

curl https://app.instica.com/api/v1/products/ \
  -H "Authorization: Bearer YOUR_TOKEN"

API key auth

curl https://app.instica.com/api/v1/products/ \
  -H "X-API-Key: YOUR_API_KEY"

Versioning

The API uses URL-based versioning. All domain resource endpoints are under /api/v1/. Authentication endpoints use the unversioned /api/auth/ prefix.

Current version: v1
Policy: Breaking changes will introduce a new version prefix (/api/v2/). Existing versions continue to work for a documented deprecation period.
Additive changes (new fields, new endpoints) are made without a version bump and are non-breaking.
Content type: Always application/json unless otherwise noted (multipart uploads, CSV downloads).

Tip: Always ignore unknown fields in responses. New fields may be added at any time without a version change.

API prefixes

# Domain resources (versioned)
/api/v1/products/
/api/v1/inventory/
/api/v1/orders/

# Auth routes (unversioned)
/api/auth/apple/
/api/auth/register/email/

# Health (public, unversioned)
/api/health/

Endpoint reference

Detailed documentation for each API domain.

Section	Key endpoints
Authentication	`POST /api/auth/apple/`, `/validate/`, `/logout/`, API keys, registration flows, password reset
Products	`GET/POST /api/v1/products/`, detail, update, image upload, marketplace presences
Inventory	`GET/POST /api/v1/inventory/`, assets, listings, bulk operations, analytics, CSV import/export
Orders & Sales	`GET /api/v1/orders/`, stats, shipment management, analytics, reports
Marketplace	Marketplace connections, import jobs, and platform listing/delisting
User & Account	`GET/PATCH /api/v1/user/me/`, preferences, password, listing eligibility, support, and device tokens
Subscriptions	Plans, subscription status, Apple IAP, Stripe billing, invoices, payment methods
Organization	Organization profile, team management, invites, addresses

Previous Documentation Home Next Authentication →

API Overview & Quickstart

Base URL

Quickstart — your first API call

1. Create an API key

2. List your products

3. Get a single inventory item

Authentication

Pagination

Filtering & ordering

Custom ordering options

Error handling

Validation error format

Rate limits

Authentication methods

Versioning

Endpoint reference