Resource Guide

Stores

Stores are schema-backed tables for dynamic data used by NiftyImages experiences. A store defines properties, and records contain values for those properties.

storeId is the store schema id returned by GET /v2/stores. It is not an image id.

API key scope

Store endpoints accept either a regular account API key or a Store API Key. A regular API key can access all stores owned by the account. A Store API Key starts with store- and can access exactly one store.

Use GET /v2/stores/access to identify what the current key can access. Store API Keys can read their assigned store and read or write records under it. Requests for other stores return 404; store creation, deletion, and schema/property changes return 403.

curl https://dev.niftyimages.com/v2/stores/access \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

List stores

Reference

List the caller's active stores with optional name search and cursor pagination. With a Store API Key, this returns only the assigned store.

curl "https://dev.niftyimages.com/v2/stores?limit=25&q=loyalty" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Get a store

Reference

Fetch store metadata, schema properties, and a live record count.

curl https://dev.niftyimages.com/v2/stores/{storeId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Create a store

Reference

Create a new store with at least one property. Unique properties define deterministic record ids. Requires an account API key; Store API Keys cannot create stores.

curl https://dev.niftyimages.com/v2/stores \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loyalty Balances",
    "properties": [
      { "name": "email", "type": "string", "required": true, "unique": true },
      { "name": "points", "type": "number", "required": true }
    ]
  }'

Update a store

Reference

Edit store-level metadata such as name, description, or record TTL. Only supplied fields are changed. Requires an account API key.

curl -X PATCH https://dev.niftyimages.com/v2/stores/{storeId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Loyalty Balances",
    "description": "Current loyalty balances for active members"
  }'

Delete a store

Reference

Soft-delete a store. Records remain in storage for future cleanup or recovery workflows. Requires an account API key.

curl -X DELETE https://dev.niftyimages.com/v2/stores/{storeId} \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Add a store property

Reference

Add a property to the store schema. Supported types include string, number, boolean, datetime, url_image, and url_link. Requires an account API key.

curl https://dev.niftyimages.com/v2/stores/{storeId}/properties \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tier",
    "type": "string",
    "required": false,
    "description": "Customer loyalty tier"
  }'

Update a store property

Reference

Edit non-structural property fields. Property name, type, and unique status are immutable.

curl -X PATCH https://dev.niftyimages.com/v2/stores/{storeId}/properties/tier \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "required": true,
    "description": "Required loyalty tier"
  }'

Delete a store property

Reference

Remove a non-unique property. Unique properties cannot be removed because they feed record id generation.

curl -X DELETE https://dev.niftyimages.com/v2/stores/{storeId}/properties/tier \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

List records

Reference

List records in a store with cursor pagination and optional sorting. Store API Keys can call this only for their assigned store.

curl "https://dev.niftyimages.com/v2/stores/{storeId}/records?limit=25&sortBy=date_created&sortDir=desc" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Get a record

Reference

Fetch a single record by its id.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/developer@example.com \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Add a record

Reference

Add one record. The request body is a dynamic JSON object whose keys match the store schema.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "points": 4200,
    "tier": "gold"
  }'

Batch upsert records

Reference

Upsert up to 100 records in one request. Each record is attempted independently.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/batch \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "email": "a@example.com", "points": 1200 },
      { "email": "b@example.com", "points": 3400 }
    ]
  }'

Patch a record

Reference

Partially update a record with JSON Merge Patch. Send only the fields to change; null unsets a value.

curl -X PATCH https://dev.niftyimages.com/v2/stores/{storeId}/records/developer@example.com \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "points": 5100,
    "tier": null
  }'

Delete a record by id

Reference

Delete a record by id. The operation is idempotent and returns a response even when the record was already gone.

curl -X DELETE https://dev.niftyimages.com/v2/stores/{storeId}/records/developer@example.com \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"

Delete a record by key

Reference

Delete a record by supplying the store's unique property values. The server computes the record id.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/delete-by-key \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "developer@example.com" }'

Look up a record by key

Reference

Find a record by unique property values using the same deterministic id rule as delete-by-key.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/lookup \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "developer@example.com" }'

Validate a record

Reference

Dry-run a candidate record through schema validation without writing it.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/validate \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "points": 4200
  }'

Search records

Reference

Filter and sort records with typed operators. Search returns up to 100 hits; narrow filters for larger datasets.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/search \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "points", "op": "gte", "value": "1000" }
    ],
    "match": "all",
    "sortBy": "points",
    "sortDir": "desc",
    "limit": 25
  }'

Count records

Reference

Count records matching filters, or count the whole store when filters are omitted.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/count \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "tier", "op": "eq", "value": "gold" }
    ]
  }'

Aggregate records

Reference

Run sum, avg, min, or max over a number property, optionally filtered.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/aggregate \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "points",
    "op": "sum",
    "filters": [
      { "field": "tier", "op": "eq", "value": "gold" }
    ]
  }'

Batch delete records

Reference

Delete up to 100 records by id in one request. Unknown ids count as already deleted.

curl https://dev.niftyimages.com/v2/stores/{storeId}/records/batch-delete \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["a@example.com", "b@example.com"]
  }'

Export records

Reference

Export up to 10,000 records as JSON or CSV.

curl "https://dev.niftyimages.com/v2/stores/{storeId}/records/export?format=csv&limit=1000" \
  -H "Authorization: Bearer $NIFTYIMAGES_API_KEY"