Skip to content
Semantico Docs

API overview

The Semantico API lets you drive catalog enrichment from your own systems — create products, trigger AI generation, track background jobs, and receive results by webhook.

For the full, per-endpoint reference (parameters, schemas, and try-it examples) see the API Reference, which is generated from Semantico’s OpenAPI schema.

Base URL

Section titled “Base URL”

All endpoints are served under:

https://api.semantico.ai/api/v1

All requests and responses use JSON unless stated otherwise.

Authentication

Section titled “Authentication”

Most endpoints require a bearer token:

Authorization: Bearer <token>

For programmatic access, use a long-lived API token. See Authentication for how to obtain and use one.

Errors

Section titled “Errors”

Semantico uses standard HTTP status codes:

Status Meaning
400 Bad Request Validation error (field-level details in the body).
401 Unauthorized Missing or invalid token.
403 Forbidden Token is valid but lacks the required permission or subscription.
404 Not Found Resource does not exist.
409 Conflict Resource already exists.

Validation errors are returned per field:

{
  "field_name": ["Human-readable validation message"]
}

Your first call

Section titled “Your first call”

List the products in your workspace:

Terminal window
curl -H "Authorization: Bearer <your-api-token>" \
  https://api.semantico.ai/api/v1/products/

Create a product from a reference:

Terminal window
curl -X POST \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"sku": "SKU-001", "name": "Acme water bottle 750ml"}' \
  "https://api.semantico.ai/api/v1/products/?locale=en-US"

Pagination

Section titled “Pagination”

List endpoints are paginated. Use page (starting at 1) and page_size (default 20):

Terminal window
curl -H "Authorization: Bearer <your-api-token>" \
  "https://api.semantico.ai/api/v1/products/?page=2&page_size=100"

Results come in results, with the page details in pagination:

{
  "pagination": {
    "links": {
      "next": "https://api.semantico.ai/api/v1/products/?page=3&page_size=100",
      "previous": "https://api.semantico.ai/api/v1/products/?page=1&page_size=100"
    },
    "total": 1250,
    "page_size": 100,
    "page": 2
  },
  "results": []
}

To read the whole catalog, follow pagination.links.next until it is null.

Custom sections in the product list

Section titled “Custom sections in the product list”

GET /products/ does not include your custom sections by default. To get them, pass their codes in sections, comma-separated or repeated:

Terminal window
curl -H "Authorization: Bearer <your-api-token>" \
  "https://api.semantico.ai/api/v1/products/?sections=short_description,colour&locale=en-US"

Each product then has a sections object with one key per requested code:

{
  "id": 1234,
  "sku": "SKU-001",
  "name": "Acme water bottle 750ml",
  "sections": {
    "short_description": "Leak-proof 750ml steel bottle that keeps drinks cold for 24h.",
    "colour": [
      { "id": 88, "reference": 12, "label": "Blue", "external_id": "blue", "color": "#2563EB", "content": "", "order": 0 }
    ]
  }
}
  • Text sections return a string. Single- and multiple-choice sections return a list of the selected options.
  • A requested section with no content for that product is null.
  • Content is returned in the requested locale. Sections that are not translated fall back to the workspace default locale.

To find a section’s code, retrieve any product with GET /products/{id}/. Each entry in its sections array includes section_definition.code.

Filtering by section value

Section titled “Filtering by section value”

Add a condition after the code to include the section and filter the list by it:

Value Returns products where the section…
code (no filter, just includes the section)
code:value equals value (case-insensitive)
code:~value contains value
code:filled has content
code:empty has no content
code:gt:5 is a number greater than 5 (also gte, lt, lte, eq)

For example, ?sections=short_description:empty,colour returns products that still have no short description, with their colour.

Long-running operations

Section titled “Long-running operations”

Generation, CSV uploads, and store syncs run in the background. These endpoints return immediately with a task_id (or background_task_id). Poll the Background tasks endpoints to follow progress, or configure a webhook to be notified when each product finishes.

Next steps

Section titled “Next steps”