Skip to main content
GET
https://api.firmly.work
/
api
/
v1
/
discovery
/
options
curl --request GET \
  --url 'https://api.firmly.work/api/v1/discovery/options' \
  --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'

{
  "options": {
    "variant_options": [
      {
        "option": "color",
        "values": ["Black", "Blue", "Brown", "Gray", "Green", "Red", "White"]
      },
      {
        "option": "size",
        "values": ["S", "M", "L", "XL", "XXL", "One Size"]
      },
      {
        "option": "material",
        "values": ["Cotton", "Leather", "Polyester", "Silk", "Wool"]
      }
    ]
  }
}
Get the available filter options for product search. Use this endpoint to populate filter UI controls and discover valid values for the Search endpoint.

​
Authentication

This endpoint requires authentication via the x-firmly-authorization header. See Browser Session Authentication for complete details on:
  • Obtaining and refreshing tokens
  • Token format and expiry
  • Required permissions
  • Device, App ID, and Developer authentication modes

​
Response

​
options
object
Container for all search filter options.

​
Error Responses

Status CodeErrorDescription
401UnauthorizedMissing or invalid x-firmly-authorization header
401TokenExpiredAuthentication token has expired. Refresh and retry.
403ForbiddenToken does not have permission for this operation
429RateLimitExceededToo many requests. Check Retry-After header.
500ErrorStoreUnavailableOptions service is temporarily unavailable
503ServiceUnavailableSystem maintenance in progress
curl --request GET \
  --url 'https://api.firmly.work/api/v1/discovery/options' \
  --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'

{
  "options": {
    "variant_options": [
      {
        "option": "color",
        "values": ["Black", "Blue", "Brown", "Gray", "Green", "Red", "White"]
      },
      {
        "option": "size",
        "values": ["S", "M", "L", "XL", "XXL", "One Size"]
      },
      {
        "option": "material",
        "values": ["Cotton", "Leather", "Polyester", "Silk", "Wool"]
      }
    ]
  }
}

​
Usage Notes

Exact matching: The values returned by this endpoint are the exact strings to use in search filters. Variant filters in the search endpoint use exact string matching, so "Blue" will not match "blue" or "Navy Blue".
Caching: Option values change infrequently. Consider caching the response for a reasonable period (e.g., 5-15 minutes) to reduce API calls.

​
Example: Building Filter UI

// Fetch available search options
const getSearchOptions = async () => {
  const response = await fetch('https://api.firmly.work/api/v1/discovery/options', {
    headers: {
      'x-firmly-authorization': authToken
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch options');
  }

  return response.json();
};

// Build filter UI from options
const buildFilterUI = async () => {
  const { options } = await getSearchOptions();

  options.variant_options.forEach(({ option, values }) => {
    console.log(`${option}: ${values.join(', ')}`);
    // Create checkbox/dropdown UI for each option
  });
};

// Use selected filters in search
const searchWithVariantFilters = async (query, selectedFilters) => {
  // selectedFilters = { color: ['Blue', 'Black'], size: ['M', 'L'] }
  const variants = Object.entries(selectedFilters).map(([option, values]) => ({
    option,
    values
  }));

  const response = await fetch('https://api.firmly.work/api/v1/discovery/search', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': authToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query,
      filters: { variants }
    })
  });

  return response.json();
};