Making API Requests

The Product Classifier API provides a single endpoint for product classification. Send a POST request with your product description and configuration options, and receive the matching category within seconds.

API Endpoint

POST https://api.productclassifier.com/api/v1/products/categorize

All requests require authentication via Bearer token. See Managing API Keys for details on creating and managing your API keys.

Complete Request Example

Here’s a request with all parameters specified:

curl -X POST https://api.productclassifier.com/api/v1/products/categorize \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Apple iPhone 16 Pro 512GB smartphone with titanium design and A18 chip",
    "taxonomy": "Google",
    "customInstructionsForAi": "For phones without contract information, default to unlocked unless description explicitly states contract or pre-paid",
    "leafsOnly": false,
    "fallbackToBestGuess": true
  }'

Request Parameters

Required Parameter

product (string, required)

The product description to classify. Include relevant details such as:

Product name and brand
Key features and specifications
Materials or construction
Use cases or target audience

{
  "product": "Nike Air Max 270 running shoes with Air cushioning technology"
}

Optional Parameters

All other parameters are optional. If omitted, the API uses default values.

taxonomy (string, optional)

The product taxonomy to use for classification.

Options: "Shopify" or "Google"
Default: "Google"

Choose the taxonomy that matches your target platform or sales channel.

{
  "taxonomy": "Shopify"
}

customInstructionsForAi (string, optional)

Natural language guidance for the AI’s decision-making process. Provide disambiguation rules, business logic, or edge case handling.

Default: null (no custom instructions)

{
  "customInstructionsForAi": "Gaming peripherals go under gaming, not general computer accessories"
}

For comprehensive guidance on writing effective instructions, see Writing Custom Instructions.

leafsOnly (boolean, optional)

Constrains classification to leaf categories only (categories with no children).

Options: true or false
Default: false

When enabled, parent categories are filtered out during candidate generation, ensuring all results are at the most specific level.

{
  "leafsOnly": true
}

fallbackToBestGuess (boolean, optional)

Returns the highest-scored candidate when the AI cannot confidently select a category.

Options: true or false
Default: false

Enables maximum coverage at the cost of some accuracy for ambiguous products.

{
  "fallbackToBestGuess": true
}

Minimal Request

Only the product parameter is required. This request uses default values for all optional parameters:

curl -X POST https://api.productclassifier.com/api/v1/products/categorize \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Leather wallet with RFID blocking"
  }'

This is equivalent to:

{
  "product": "Leather wallet with RFID blocking",
  "taxonomy": "Google",
  "customInstructionsForAi": null,
  "leafsOnly": false,
  "fallbackToBestGuess": false
}

Response Structure

Successful classifications return JSON with the following structure:

{
  "success": true,
  "categoryFound": true,
  "categoryId": "267",
  "categoryPath": "Electronics > Communications > Telephony > Mobile Phones",
  "categoryLine": "267 - Electronics > Communications > Telephony > Mobile Phones",
  "categoryTags": [
    "Electronics",
    "Communications",
    "Telephony",
    "Mobile Phones"
  ],
  "confidenceLevel": "AI"
}

Response Fields

success (boolean)

Indicates whether the API request was processed successfully. true means the request was valid and processed; falseindicates an error occurred.

categoryFound (boolean)

Indicates whether a category was returned. false when the AI cannot confidently select a category and fallbackToBestGuess is disabled.

categoryId (string)

The unique identifier for the category. Use this ID to match categories across requests or store in your database.

categoryPath (string)

The full hierarchy from root to the selected category, separated by >. Shows the category’s position in the taxonomy tree.

categoryLine (string)

Combines categoryId and categoryPath in the format: ID - Path. Useful for display purposes.

categoryTags (array of strings)

Each level of the category hierarchy as separate array elements. Useful for breadcrumb navigation or filtering.

confidenceLevel (string)

Indicates how the category was determined:

"AI" - AI confidently selected this category (highest confidence)
"RelevantCategory" - Top-ranked candidate used when AI couldn’t decide (lower confidence)
"None" - No category found

error (string)

An error message describing what went wrong. Only present when success is false.

For detailed information about confidence levels and what they mean, see Error Handling and Response Codes.

No Category Found Response

When categoryFound is false:

{
  "success": true,
  "categoryFound": false,
  "categoryId": null,
  "categoryPath": null,
  "categoryLine": null,
  "categoryTags": [],
  "confidenceLevel": "None"
}

This occurs when the AI cannot confidently select a category and fallbackToBestGuess is disabled. Consider:

Adding more detail to the product description
Enabling fallbackToBestGuess
Providing custom instructions for edge cases

Error Responses

When success is false, the response includes an error message:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common error scenarios:

401 Unauthorized - Invalid or missing API key
400 Bad Request - Missing required product parameter or invalid parameter values
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server-side error occurred

For complete details on error codes, troubleshooting, and handling errors gracefully, see Error Handling and Response Codes.

Parameter Configuration Strategies

The optional parameters work together to control classification behavior. For guidance on choosing the right configuration for your use case, see Classification Strategies.

Common patterns:

Maximum Coverage - Get results for every product:

{
  "leafsOnly": false,
  "fallbackToBestGuess": true
}

Precision First - Only return highly confident results:

{
  "leafsOnly": false,
  "fallbackToBestGuess": false
}

Specific Categories Required - Always return leaf-level categories:

{
  "leafsOnly": true,
  "fallbackToBestGuess": true
}

API Specification

For complete technical details including request/response schemas, data types, and validation rules, see the API specification.

Next Steps

Managing API Keys - Create, rotate, and manage your API keys
Rate Limits & Usage Quotas - Understand your plan’s limits and credit consumption
Error Handling and Response Codes - Troubleshoot issues and handle errors
Classification Strategies - Choose the right configuration for your use case

Managing API Keys Rate Limits & Usage Quotas