POST /coverage/url-lists/{urlListId}/urls

POST /coverage/url-lists/{urlListId}/urls adds product URLs to a list. It is an idempotent set-add: re-adding a URL that is already a member is accepted and changes nothing. Every URL is normalized server-side before storage — the scheme and host are lowercased, fragments and trailing slashes are dropped, and tracking parameters (utm_* and similar) are stripped while meaningful query parameters are preserved. Membership is keyed on the normalized form, so two submitted variants that normalize identically store one entry. URLs that cannot be normalized as product URLs are rejected per URL with code invalid_url without failing the batch.

Request

POST https://api.octogen.ai/v1/coverage/url-lists/{urlListId}/urls
Authorization: Bearer <your-platform-api-key>
Content-Type: application/json

Path parameters

string

required

The list id (cul_...).

Body parameters

string[]

required

1–1,000 product URLs per request, each at most 2,048 characters. Each entry must be an absolute http(s) URL.

Example

curl -sS https://api.octogen.ai/v1/coverage/url-lists/cul_01KZAC9QSY5RWSTZ63FGBS50F2/urls \
  -H "Authorization: Bearer $OCTOGEN_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://shop.example/products/dress?utm_source=newsletter"]}'

Response

array

required

One entry per stored URL: url as you sent it and the normalizedUrl that was stored.

array

required

One entry per rejected URL with a stable code (invalid_url) and a safe message.

integer

required

The list’s total URL count after this request.

string

required

Identifier for this mutation, useful in support requests.

Example response

{
  "accepted": [
    {
      "url": "https://shop.example/products/dress?utm_source=newsletter",
      "normalizedUrl": "https://shop.example/products/dress"
    }
  ],
  "rejected": [],
  "urlCount": 5445,
  "requestId": "9f0f5a3f-6a3f-4a3d-9d3c-1b2a3c4d5e6f"
}

Errors

Status	`detail`	Meaning
`404`	`"url_list_not_found"`	No list with that id exists in your organization.
`409`	`"url_list_deleting"`	The list is being deleted; mutations are refused.
`409`	`"url_list_migrating"`	The list’s entries are being re-normalized; retry shortly.
`409`	`"list_url_capacity_exceeded"`	The add would exceed 100,000 entries. The whole request is refused.
`503`	`"url_lists_unavailable"`	The feature is temporarily unavailable. Retry with backoff.

SDK equivalents

import asyncio
from octogen_ai_sdk import OctogenClient

async def main() -> None:
    async with OctogenClient() as client:
        result = await client.add_coverage_url_list_urls(
            "cul_01KZAC9QSY5RWSTZ63FGBS50F2",
            urls=["https://shop.example/products/dress?utm_source=newsletter"],
        )
        print(result.url_count, [r.code for r in result.rejected])

asyncio.run(main())

import { OctogenClient } from "@octogen-ai/sdk";

const client = new OctogenClient();
const result = await client.addCoverageUrlListUrls(
  "cul_01KZAC9QSY5RWSTZ63FGBS50F2",
  ["https://shop.example/products/dress?utm_source=newsletter"],
);
console.log(result.urlCount, result.rejected.map((r) => r.code));

Catalog API

Voyage API

Coverage API

Data Models

POST /coverage/url-lists/{urlListId}/urls — add URLs

Request

Path parameters

Body parameters

Example

Response

Example response

Errors

SDK equivalents

​Request

​Path parameters

​Body parameters

​Example

​Response

​Example response

​Errors

​SDK equivalents

Request

Path parameters

Body parameters

Example

Response

Example response

Errors

SDK equivalents