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"

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”