API Documentation

Base URL: https://api.masalasearch.com/v1

// All responses follow this envelope: { "data": ..., "meta": { "total": 100, "limit": 50, "offset": 0 }, "error": null }

Authentication

All endpoints require a Bearer token. Write operations require specific scopes (e.g. products:write). An admin:write key bypasses all individual scope checks.

# Include on every request:
Authorization: Bearer msk_your_api_key_here
curl "https://api.masalasearch.com/v1/search?q=masala" \
  -H "Authorization: Bearer msk_..."
Missing or invalid token → 401 Unauthorized. Missing scope → 403 Forbidden.

Rate Limits

Two layers of enforcement:

  • IP-level: 120 requests / 60 s per IP (Upstash Redis sliding window)
  • Key-level: hourly + monthly quotas set per key at creation time
PlanHourly LimitMonthly Limit
Developer (Free)1,000 / hour100,000 / month
Business10,000 / hour1,000,000 / month
EnterpriseUnlimitedUnlimited

When exceeded → 429 Too Many Requests with a Retry-After header.

Scopes

Each API key carries a list of scopes. admin:write grants full access to everything.

ScopeAccess
admin:writeFull read + write access to every endpoint (superscope)
adminRead-only access to every endpoint
products / products:writeProducts resource
listings / listings:writeListings resource
searchSearch endpoint only
stores / stores:writeStores resource
brands / brands:writeBrands resource
categories / categories:writeCategories resource
brand_aliases / brand_aliases:writeBrand aliases
product_aliases / product_aliases:writeProduct aliases
category_aliases / category_aliases:writeCategory aliases
category_rules / category_rules:writeCategory rules
product_categories / product_categories:writeProduct–category assignments
product_merges / product_merges:writeProduct merge records
contact_messages / contact_messages:writeContact form messages
Core

Products

GET/products
scope: products

Paginated list of products. Includes brand details.

Query Parameters

limitMax 200 (default: 50)
offsetPagination offset
searchCase-insensitive name filter
brand_idFilter by brand UUID
category_idFilter by category UUID

Example

curl "https://api.masalasearch.com/v1/products?search=masala" \
  -H "Authorization: Bearer msk_..."
GET/products/[id]
scope: products

Single product by UUID. Includes brand, active listings, and assigned categories.

Example

curl "https://api.masalasearch.com/v1/products/40169688-939a-4287-ad5f-844559d6faf0" \
  -H "Authorization: Bearer msk_..."
GET/products/[id]/priceHistory
scope: products

Full price history for a product across all store listings.

Query Parameters

daysDays back (default: 30)
store_idFilter to a specific store UUID

Example

curl "https://api.masalasearch.com/v1/products/[id]/priceHistory?days=90" \
  -H "Authorization: Bearer msk_..."
POST/products
scope: products:write

Create a new product.

Request Body

{
  "canonical_name": "Garam Masala",  // required
  "brand_id": "uuid...",
  "size_label": "100g",
  "weight_g": 100
}

Example

curl -X POST "https://api.masalasearch.com/v1/products" \
  -H "Authorization: Bearer msk_..." \
  -d '{"canonical_name":"Garam Masala"}'
PATCH/products/[id]
scope: products:write

Partially update a product. All fields optional.

Example

curl -X PATCH "https://api.masalasearch.com/v1/products/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"size_label":"200g"}'
DELETE/products/[id]
scope: products:write

Delete a product by UUID. Returns 404 if not found.

Example

curl -X DELETE "https://api.masalasearch.com/v1/products/uuid-here" \
  -H "Authorization: Bearer msk_..."

Listings

Listings represent the actual products sold by stores, including their current price and URL. Querying listings across different stores for the same product is the recommended approach for building a Price Comparison feature.

GET/listings
scope: listings

All listings with price filtering and sorting.

Query Parameters

store_idFilter by store UUID
product_idFilter by product UUID
min_priceMinimum price
max_priceMaximum price
sortprice | price_per_100g | price_per_liter | last_seen_at
activetrue (default) — false to include inactive

Example

curl "https://api.masalasearch.com/v1/listings?sort=price_per_100g&limit=20" \
  -H "Authorization: Bearer msk_..."
GET/listings/[id]
scope: listings

Single listing by UUID.

Example

curl "https://api.masalasearch.com/v1/listings/uuid-here" \
  -H "Authorization: Bearer msk_..."
GET/listings/[id]/priceHistory
scope: listings

Price history for a single listing.

Query Parameters

daysDays back (default: 30)
limitMax records (default: 1000)

Example

curl "https://api.masalasearch.com/v1/listings/uuid-here/priceHistory?days=90" \
  -H "Authorization: Bearer msk_..."
POST/listings
scope: listings:write

Create a new listing.

Request Body

{
  "store_id": "uuid...", // required UUID
  "url": "https://...", // required
  "title": "Basmati 1kg", // required
  "price": 2.99          // required
}

Example

curl -X POST "https://api.masalasearch.com/v1/listings" \
  -H "Authorization: Bearer msk_..." \
  -d '{"store_id":"uuid...","url":"https://...","title":"Basmati 1kg","price":2.99}'
PATCH/listings/[id]
scope: listings:write

Update a listing.

Example

curl -X PATCH "https://api.masalasearch.com/v1/listings/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"price":3.49}'
DELETE/listings/[id]
scope: listings:write

Delete a listing by UUID.

Example

curl -X DELETE "https://api.masalasearch.com/v1/listings/uuid-here" \
  -H "Authorization: Bearer msk_..."

Stores

GET/stores
scope: stores

All stores ordered by name.

Example

curl "https://api.masalasearch.com/v1/stores" \
  -H "Authorization: Bearer msk_..."
GET/stores/[id]
scope: stores

Single store by UUID.

Example

curl "https://api.masalasearch.com/v1/stores/uuid-here" \
  -H "Authorization: Bearer msk_..."
GET/stores/[id]/listings
scope: stores

Full product catalogue for a store.

Query Parameters

sortprice | price_per_100g | price_per_liter | title | last_seen_at
limitMax 200 (default: 50)
activetrue (default)

Example

curl "https://api.masalasearch.com/v1/stores/uuid-here/listings" \
  -H "Authorization: Bearer msk_..."
POST/stores
scope: stores:write

Create a store.

Request Body

{
  "name": "Little India", // required
  "base_url": "https://...",
  "enabled": true
}

Example

curl -X POST "https://api.masalasearch.com/v1/stores" \
  -H "Authorization: Bearer msk_..." \
  -d '{"name":"Little India","enabled":true}'
PATCH/stores/[id]
scope: stores:write

Update a store.

Example

curl -X PATCH "https://api.masalasearch.com/v1/stores/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"enabled":false}'
DELETE/stores/[id]
scope: stores:write

Delete a store by UUID.

Example

curl -X DELETE "https://api.masalasearch.com/v1/stores/uuid-here" \
  -H "Authorization: Bearer msk_..."

Brands

GET/brands
scope: brands

Paginated list of all brands.

Query Parameters

searchFilter by name

Example

curl "https://api.masalasearch.com/v1/brands?search=shan" \
  -H "Authorization: Bearer msk_..."
GET/brands/[id]
scope: brands

Single brand by UUID.

Example

curl "https://api.masalasearch.com/v1/brands/uuid-here" \
  -H "Authorization: Bearer msk_..."
GET/brands/[id]/products
scope: brands

All products belonging to a brand.

Example

curl "https://api.masalasearch.com/v1/brands/uuid-here/products" \
  -H "Authorization: Bearer msk_..."
POST/brands
scope: brands:write

Create a brand.

Request Body

{
  "name": "Shan", // required
  "slug": "shan"  // required
}

Example

curl -X POST "https://api.masalasearch.com/v1/brands" \
  -H "Authorization: Bearer msk_..." \
  -d '{"name":"Shan","slug":"shan"}'
PATCH/brands/[id]
scope: brands:write

Update a brand.

Example

curl -X PATCH "https://api.masalasearch.com/v1/brands/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"country":"Pakistan"}'
DELETE/brands/[id]
scope: brands:write

Delete a brand.

Example

curl -X DELETE "https://api.masalasearch.com/v1/brands/uuid-here" \
  -H "Authorization: Bearer msk_..."

Categories

GET/categories
scope: categories

All categories ordered by sort_order. Includes parent_id for building a category tree.

Example

curl "https://api.masalasearch.com/v1/categories" \
  -H "Authorization: Bearer msk_..."
GET/categories/[id]
scope: categories

Single category by UUID.

Example

curl "https://api.masalasearch.com/v1/categories/uuid-here" \
  -H "Authorization: Bearer msk_..."
GET/categories/[id]/products
scope: categories

Paginated products within a category.

Example

curl "https://api.masalasearch.com/v1/categories/uuid-here/products" \
  -H "Authorization: Bearer msk_..."
POST/categories
scope: categories:write

Create a category.

Request Body

{
  "name": "Spices",  // required
  "slug": "spices",  // required
  "parent_id": null  // optional UUID
}

Example

curl -X POST "https://api.masalasearch.com/v1/categories" \
  -H "Authorization: Bearer msk_..." \
  -d '{"name":"Spices","slug":"spices"}'
PATCH/categories/[id]
scope: categories:write

Update a category.

Example

curl -X PATCH "https://api.masalasearch.com/v1/categories/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"sort_order":10}'
DELETE/categories/[id]
scope: categories:write

Delete a category.

Example

curl -X DELETE "https://api.masalasearch.com/v1/categories/uuid-here" \
  -H "Authorization: Bearer msk_..."
Domain Data

Brand Aliases

Alternative names for a brand used during data normalization (e.g. “MDH Foods” → brand MDH).
GET/brand-aliases
scope: brand_aliases

List all brand aliases.

Example

curl "https://api.masalasearch.com/v1/brand-aliases" \
  -H "Authorization: Bearer msk_..."
GET/brand-aliases/[id]
scope: brand_aliases

Single brand alias by UUID.

Example

curl "https://api.masalasearch.com/v1/brand-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/brand-aliases
scope: brand_aliases:write

Create a brand alias.

Request Body

{
  "brand_id": "uuid...", // required UUID
  "alias": "MDH Foods"  // required
}

Example

curl -X POST "https://api.masalasearch.com/v1/brand-aliases" \
  -H "Authorization: Bearer msk_..." \
  -d '{"brand_id":"uuid...","alias":"MDH Foods"}'
PATCH/brand-aliases/[id]
scope: brand_aliases:write

Update a brand alias.

Example

curl -X PATCH "https://api.masalasearch.com/v1/brand-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"alias":"MDH Spices"}'
DELETE/brand-aliases/[id]
scope: brand_aliases:write

Delete a brand alias.

Example

curl -X DELETE "https://api.masalasearch.com/v1/brand-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..."

Product Aliases

Alternative names for a product used during ingestion deduplication.
GET/product-aliases
scope: product_aliases

List all product aliases.

Example

curl "https://api.masalasearch.com/v1/product-aliases" \
  -H "Authorization: Bearer msk_..."
GET/product-aliases/[id]
scope: product_aliases

Single product alias.

Example

curl "https://api.masalasearch.com/v1/product-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/product-aliases
scope: product_aliases:write

Create a product alias.

Request Body

{
  "product_id": "uuid...", // required UUID
  "alias": "Basmati Rice"  // required
}

Example

curl -X POST "https://api.masalasearch.com/v1/product-aliases" \
  -H "Authorization: Bearer msk_..." \
  -d '{"product_id":"uuid...","alias":"Basmati Rice"}'
PATCH/product-aliases/[id]
scope: product_aliases:write

Update a product alias.

Example

curl -X PATCH "https://api.masalasearch.com/v1/product-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"alias":"Premium Basmati"}'
DELETE/product-aliases/[id]
scope: product_aliases:write

Delete a product alias.

Example

curl -X DELETE "https://api.masalasearch.com/v1/product-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..."

Category Aliases

Alternative names for a category used during auto-categorization.
GET/category-aliases
scope: category_aliases

List all category aliases.

Example

curl "https://api.masalasearch.com/v1/category-aliases" \
  -H "Authorization: Bearer msk_..."
GET/category-aliases/[id]
scope: category_aliases

Single category alias.

Example

curl "https://api.masalasearch.com/v1/category-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/category-aliases
scope: category_aliases:write

Create a category alias.

Request Body

{
  "category_id": "uuid...", // required UUID
  "alias": "Dal & Lentils"  // required
}

Example

curl -X POST "https://api.masalasearch.com/v1/category-aliases" \
  -H "Authorization: Bearer msk_..." \
  -d '{"category_id":"uuid...","alias":"Dal & Lentils"}'
PATCH/category-aliases/[id]
scope: category_aliases:write

Update a category alias.

Example

curl -X PATCH "https://api.masalasearch.com/v1/category-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"alias":"Lentils"}'
DELETE/category-aliases/[id]
scope: category_aliases:write

Delete a category alias.

Example

curl -X DELETE "https://api.masalasearch.com/v1/category-aliases/uuid-here" \
  -H "Authorization: Bearer msk_..."

Category Rules

Rules that drive the auto-categorization engine (e.g. if product name contains “masala”, assign category “Spices”).
GET/category-rules
scope: category_rules

List all category rules.

Example

curl "https://api.masalasearch.com/v1/category-rules" \
  -H "Authorization: Bearer msk_..."
GET/category-rules/[id]
scope: category_rules

Single rule by UUID.

Example

curl "https://api.masalasearch.com/v1/category-rules/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/category-rules
scope: category_rules:write

Create a categorization rule.

Request Body

{
  "category_id": "uuid...", // required UUID
  "field": "canonical_name",
  "operator": "contains",
  "value": "masala",
  "priority": 10
}

Example

curl -X POST "https://api.masalasearch.com/v1/category-rules" \
  -H "Authorization: Bearer msk_..." \
  -d '{"category_id":"uuid...","field":"canonical_name","operator":"contains","value":"masala"}'
PATCH/category-rules/[id]
scope: category_rules:write

Update a rule.

Example

curl -X PATCH "https://api.masalasearch.com/v1/category-rules/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"priority":20}'
DELETE/category-rules/[id]
scope: category_rules:write

Delete a rule.

Example

curl -X DELETE "https://api.masalasearch.com/v1/category-rules/uuid-here" \
  -H "Authorization: Bearer msk_..."

Product Categories

Many-to-many assignments linking products to categories. Uses a composite key — single-item routes need both [product_id] and [category_id].
GET/product-categories
scope: product_categories

List all product–category assignments.

Example

curl "https://api.masalasearch.com/v1/product-categories" \
  -H "Authorization: Bearer msk_..."
GET/product-categories/[product_id]/[category_id]
scope: product_categories

Single assignment by composite key.

Example

curl "https://api.masalasearch.com/v1/product-categories/p-uuid/c-uuid" \
  -H "Authorization: Bearer msk_..."
POST/product-categories
scope: product_categories:write

Assign a product to a category.

Request Body

{
  "product_id": "uuid...",   // required UUID
  "category_id": "uuid...", // required UUID
  "is_primary": false,
  "review_status": "pending"
}

Example

curl -X POST "https://api.masalasearch.com/v1/product-categories" \
  -H "Authorization: Bearer msk_..." \
  -d '{"product_id":"p-uuid","category_id":"c-uuid"}'
PATCH/product-categories/[product_id]/[category_id]
scope: product_categories:write

Update an assignment.

Example

curl -X PATCH "https://api.masalasearch.com/v1/product-categories/p-uuid/c-uuid" \
  -H "Authorization: Bearer msk_..." \
  -d '{"is_primary":true}'
DELETE/product-categories/[product_id]/[category_id]
scope: product_categories:write

Remove a product from a category.

Example

curl -X DELETE "https://api.masalasearch.com/v1/product-categories/p-uuid/c-uuid" \
  -H "Authorization: Bearer msk_..."

Product Merges

Maps a source product name (from a store) to a canonical product for deduplication during ingestion.
GET/product-merges
scope: product_merges

List all merge records.

Example

curl "https://api.masalasearch.com/v1/product-merges" \
  -H "Authorization: Bearer msk_..."
GET/product-merges/[id]
scope: product_merges

Single merge record.

Example

curl "https://api.masalasearch.com/v1/product-merges/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/product-merges
scope: product_merges:write

Create a merge mapping.

Request Body

{
  "source_canonical_name": "Basmati 1kg", // required
  "target_product_id": "uuid...",         // required UUID
  "source_brand_id": "uuid...",           // optional UUID
  "source_size_label": "1kg"
}

Example

curl -X POST "https://api.masalasearch.com/v1/product-merges" \
  -H "Authorization: Bearer msk_..." \
  -d '{"source_canonical_name":"Basmati 1kg","target_product_id":"uuid..."}'
PATCH/product-merges/[id]
scope: product_merges:write

Update a merge record.

Example

curl -X PATCH "https://api.masalasearch.com/v1/product-merges/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"source_size_label":"1000g"}'
DELETE/product-merges/[id]
scope: product_merges:write

Delete a merge record.

Example

curl -X DELETE "https://api.masalasearch.com/v1/product-merges/uuid-here" \
  -H "Authorization: Bearer msk_..."

Contact Messages

Contact form submissions. POST is intended to be called server-side with an env-stored admin token.
GET/contact-messages
scope: contact_messages

List all contact messages.

Example

curl "https://api.masalasearch.com/v1/contact-messages" \
  -H "Authorization: Bearer msk_..."
GET/contact-messages/[id]
scope: contact_messages

Single message by UUID.

Example

curl "https://api.masalasearch.com/v1/contact-messages/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/contact-messages
scope: contact_messages:write

Submit a contact message.

Request Body

{
  "name": "Jane Doe",          // required
  "email": "jane@example.com", // required email
  "message": "Hello!"         // required
}

Example

curl -X POST "https://api.masalasearch.com/v1/contact-messages" \
  -H "Authorization: Bearer msk_..." \
  -d '{"name":"Jane","email":"jane@example.com","message":"Hello!"}'
PATCH/contact-messages/[id]
scope: contact_messages:write

Update a message.

Example

curl -X PATCH "https://api.masalasearch.com/v1/contact-messages/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"message":"Updated"}'
DELETE/contact-messages/[id]
scope: contact_messages:write

Delete a message.

Example

curl -X DELETE "https://api.masalasearch.com/v1/contact-messages/uuid-here" \
  -H "Authorization: Bearer msk_..."
Admin
All admin endpoints require admin scope for reads and admin:write for mutations.

API Keys

When creating a key, the server generates a msk_-prefixed key and returns it once only. Only a SHA-256 hash is stored.
GET/api-keys
scope: admin

List all API key records (hashes only).

Example

curl "https://api.masalasearch.com/v1/api-keys" \
  -H "Authorization: Bearer msk_..."
GET/api-keys/[id]
scope: admin

Single API key by UUID.

Example

curl "https://api.masalasearch.com/v1/api-keys/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/api-keys
scope: admin:write

Issue a new API key. Raw key returned once — store it immediately.

Request Body

{
  "user_id": "uuid...",             // required UUID
  "name": "My App Key",            // optional
  "scopes": ["products","search"],  // required
  "rate_limit": 1000,              // hourly limit
  "monthly_limit": 100000
}

Example

curl -X POST "https://api.masalasearch.com/v1/api-keys" \
  -H "Authorization: Bearer msk_..." \
  -d '{"user_id":"uuid...","scopes":["products","search"]}'
PATCH/api-keys/[id]
scope: admin:write

Update a key (e.g. disable it, change scopes).

Example

curl -X PATCH "https://api.masalasearch.com/v1/api-keys/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"is_active":false}'
DELETE/api-keys/[id]
scope: admin:write

Permanently delete an API key.

Example

curl -X DELETE "https://api.masalasearch.com/v1/api-keys/uuid-here" \
  -H "Authorization: Bearer msk_..."

Crawl Jobs

GET/crawl-jobs
scope: admin

List all crawl job records.

Example

curl "https://api.masalasearch.com/v1/crawl-jobs" \
  -H "Authorization: Bearer msk_..."
GET/crawl-jobs/[id]
scope: admin

Single crawl job.

Example

curl "https://api.masalasearch.com/v1/crawl-jobs/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/crawl-jobs
scope: admin:write

Create a crawl job record.

Request Body

{
  "store_id": "uuid...", // required UUID
  "status": "running"   // default
}

Example

curl -X POST "https://api.masalasearch.com/v1/crawl-jobs" \
  -H "Authorization: Bearer msk_..." \
  -d '{"store_id":"uuid..."}'
PATCH/crawl-jobs/[id]
scope: admin:write

Update a crawl job.

Example

curl -X PATCH "https://api.masalasearch.com/v1/crawl-jobs/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"status":"completed","listings_found":1200}'
DELETE/crawl-jobs/[id]
scope: admin:write

Delete a crawl job record.

Example

curl -X DELETE "https://api.masalasearch.com/v1/crawl-jobs/uuid-here" \
  -H "Authorization: Bearer msk_..."

Crawler Paths

GET/crawler-paths
scope: admin

List all crawler paths.

Example

curl "https://api.masalasearch.com/v1/crawler-paths" \
  -H "Authorization: Bearer msk_..."
GET/crawler-paths/[id]
scope: admin

Single crawler path.

Example

curl "https://api.masalasearch.com/v1/crawler-paths/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/crawler-paths
scope: admin:write

Add a crawler path for a store.

Request Body

{
  "store_id": "uuid...", // required UUID
  "path": "/products",  // required
  "sort_order": 0
}

Example

curl -X POST "https://api.masalasearch.com/v1/crawler-paths" \
  -H "Authorization: Bearer msk_..." \
  -d '{"store_id":"uuid...","path":"/products"}'
PATCH/crawler-paths/[id]
scope: admin:write

Update a crawler path.

Example

curl -X PATCH "https://api.masalasearch.com/v1/crawler-paths/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"sort_order":5}'
DELETE/crawler-paths/[id]
scope: admin:write

Delete a crawler path.

Example

curl -X DELETE "https://api.masalasearch.com/v1/crawler-paths/uuid-here" \
  -H "Authorization: Bearer msk_..."

Job Queue

GET/job-queue
scope: admin

List queued crawl jobs.

Example

curl "https://api.masalasearch.com/v1/job-queue" \
  -H "Authorization: Bearer msk_..."
GET/job-queue/[id]
scope: admin

Single queued job.

Example

curl "https://api.masalasearch.com/v1/job-queue/uuid-here" \
  -H "Authorization: Bearer msk_..."
POST/job-queue
scope: admin:write

Enqueue a store for crawling.

Request Body

{
  "store_id": "uuid..." // required UUID
}

Example

curl -X POST "https://api.masalasearch.com/v1/job-queue" \
  -H "Authorization: Bearer msk_..." \
  -d '{"store_id":"uuid..."}'
PATCH/job-queue/[id]
scope: admin:write

Update a queued job.

Example

curl -X PATCH "https://api.masalasearch.com/v1/job-queue/uuid-here" \
  -H "Authorization: Bearer msk_..." \
  -d '{"store_id":"uuid..."}'
DELETE/job-queue/[id]
scope: admin:write

Remove a job from the queue.

Example

curl -X DELETE "https://api.masalasearch.com/v1/job-queue/uuid-here" \
  -H "Authorization: Bearer msk_..."

Settings

Global key-value settings. The ID for single-item operations is the setting key string (not a UUID).
GET/settings
scope: admin

List all settings.

Example

curl "https://api.masalasearch.com/v1/settings" \
  -H "Authorization: Bearer msk_..."
GET/settings/[key]
scope: admin

Single setting by key string.

Example

curl "https://api.masalasearch.com/v1/settings/crawler_enabled" \
  -H "Authorization: Bearer msk_..."
POST/settings
scope: admin:write

Create a setting.

Request Body

{
  "key": "crawler_enabled", // required string
  "value": "true"           // required string
}

Example

curl -X POST "https://api.masalasearch.com/v1/settings" \
  -H "Authorization: Bearer msk_..." \
  -d '{"key":"crawler_enabled","value":"true"}'
PATCH/settings/[key]
scope: admin:write

Update a setting.

Example

curl -X PATCH "https://api.masalasearch.com/v1/settings/crawler_enabled" \
  -H "Authorization: Bearer msk_..." \
  -d '{"value":"false"}'
DELETE/settings/[key]
scope: admin:write

Delete a setting.

Example

curl -X DELETE "https://api.masalasearch.com/v1/settings/crawler_enabled" \
  -H "Authorization: Bearer msk_..."
Reference

Error Reference

All errors: { "data": null, "meta": null, "error": { "code": "...", "message": "..." } }

codeHTTPDescription
UNAUTHORIZED401Missing/invalid Authorization header or revoked key
FORBIDDEN403API key lacks the required scope
MISSING_QUERY400Required ?q= param is missing (search only)
INVALID_ID400ID is not a valid UUID (or empty string for settings key)
VALIDATION_ERROR400Body failed Zod validation — check error.details for field errors
NOT_FOUND404Resource does not exist
METHOD_NOT_ALLOWED405HTTP method not supported on this endpoint
QUOTA_EXCEEDED429Monthly request quota exhausted
RATE_LIMITED429Hourly key limit or IP limit exceeded — see Retry-After header
DB_ERROR500Unexpected internal database error
DocsTermsPrivacy