Skip to main content
POST /products/refresh requests a fresh update for specific products. Use it when you need Octogen to refresh a known set of product pages sooner than the standard catalog update cadence. The endpoint returns as soon as the request is accepted; it does not wait for downstream processing or indexing to finish.

​
Request

POST https://api.octogen.ai/v1/products/refresh
Authorization: Bearer <your-platform-api-key>
Content-Type: application/json

​
Body parameters

​
targets
object[]
required
Product identifiers to refresh. Maximum 500 targets per request.
​
targets[].url
string
Product page URL to refresh. Provide either url or uuid, not both.
​
targets[].uuid
string
Octogen product UUID to refresh. Provide either uuid or url, not both.
​
targets[].catalog
string
Optional catalog key. Include this when the URL is not already indexed, or when the same URL could belong to more than one granted catalog.

​
Example

curl -sS https://api.octogen.ai/v1/products/refresh \
  -H "Authorization: Bearer $OCTOGEN_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {"url": "https://warrenlotas.com/products/black-hoodie"},
      {"uuid": "11111111-1111-4111-8111-111111111111"},
      {
        "catalog": "warrenlotas",
        "url": "https://warrenlotas.com/products/new-drop"
      }
    ]
  }'

​
Response

The endpoint returns 202 Accepted when at least one target was accepted for refresh. It returns 400 Bad Request with the same response shape when no target could be accepted.
​
requestId
string
required
Request identifier for this refresh request.
​
submitted
integer
required
Number of targets received in the request.
​
workflowId
string | null
Provider-neutral workflow identifier for the asynchronous refresh, when a workflow was started.
​
workflowError
string | null
Non-fatal workflow launch error. If this is present, accepted targets were still accepted, but Octogen could not start the downstream refresh workflow automatically.
​
accepted
object[]
required
Targets accepted for refresh after authorization and validation.
​
rejected
object[]
required
Targets that were not accepted. Each rejection includes the original target, a machine-readable code, and a human-readable message.

​
Example response

{
  "requestId": "62cf3df6-30f2-4c0e-b13d-fc509bba8d4f",
  "submitted": 3,
  "workflowId": "4b4b68de-65f3-4f79-af57-a4a1d6ef4e13",
  "workflowError": null,
  "accepted": [
    {
      "catalog": "warrenlotas",
      "url": "https://warrenlotas.com/products/black-hoodie"
    }
  ],
  "rejected": [
    {
      "target": {
        "url": "https://unknown.example/products/1"
      },
      "code": "product_not_found",
      "message": "No active product matched that URL in granted catalogs."
    }
  ]
}

​
Resolution rules

TargetBehavior
{"uuid": "..."}Finds the product UUID within your granted catalogs and refreshes its canonical productUrl.
{"catalog": "...", "uuid": "..."}Finds the UUID only in the requested granted catalog.
{"url": "..."}Finds the URL in your granted catalogs. If multiple catalogs match, the target is rejected with ambiguous_url.
{"catalog": "...", "url": "..."}Refreshes the URL for that granted catalog, even if the product is not indexed yet.

​
Errors

Statusdetail or rejection codeMeaning
400response body with rejected targetsNo target could be accepted.
403"catalog_not_granted"The request named a catalog your API key cannot access.
422validation error arrayThe body is malformed, has more than 500 targets, or a target contains both url and uuid.
503"product_refresh_unavailable"Octogen could not start product refresh processing. Retry later.
Product refresh is asynchronous. Search and lookup results update after downstream processing and indexing complete.