Introduction

The Cernel API exposes resources found through the platform and is hosted at

All endpoints documented below are relative to this host. Most endpoints require an existing configuration setup of a site through the platform.

Authentication

The API uses Token-based authentication, and all requests must include the ‘Authorization’ header.

Tokens are issued per-user through the Cernel platform.

All webhooks hash the payload through the 'X-Signature-SHA256' header using the Token provided per-request. This can be used to verify the payload.

All webhooks return per element in a job. Queing a job of 100 unique elements returns 100 webhook responses with the element IDs.

Example token:

application/json

application/json

Authorization': Token 5172cd49ebea46a4bd3b9282624694d7a0e32591

Authorization': Token 5172cd49ebea46a4bd3b9282624694d7a0e32591

Rate limits

Rate limits are applied per domain and returns HTTP 429 responses when exceeded. It is recommended to start updates in batches.

Each site can have a maximum of 2500 products and 500 categories queued at once.

The system limits the following endpoints to 10 requests/m.

POST

/products

POST

/categories

The system limits the following endpoints to 1 request/s.

GET

/jobs/<str:job_id>

GET

/jobs

Endpoints

Product updates

Request body

Cernel uses identifiers to generate products, which allows for updates through the API.

Response body

The request returns the state of the queued job and the corresponding UUID4 job id that is a global and unique identifier used to fetch the job resource.

Webhooks

Product webhooks can be configured through the platform. Upon job completion the webhook returns data to the webhook URL.

Endpoint

POST

/products

Request samples

Payload:

application/json

application/json

{

"domain": "https://cernel.shop.dk,

"site_id": 0,
"products": [
{
"number": "3131a"
},
{
"number": "a6718-hg"
}
]
}

{

"domain": "https://cernel.shop.dk,

"site_id": 0,
"products": [
{
"number": "3131a"
},
{
"number": "a6718-hg"
}
]
}

Response samples

Status 202:

application/json

application/json

{
"status": "queued"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

{
"status": "queued"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

Status 4xx:

application/json

application/json

{
"status": "failure"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

{
"status": "failure"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

Webhook

application/json

application/json

{
"id": "3131a",

"domain": "https://cernel.shop.dk",

"site_id": 0,

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",
"name": "SAGA Baristamaskine (Sort)",
"language": "Danish",
"short_description": "<p>Short description</p>",
"description": "<p>Long description</p>",
"meta_title": "Meta title content",
"meta_description": "Meta description content",
"alt_text": "Alt text content",
"status": "SUCCESS",
"report": <h2>Product generation Report</h2>

<p>Generation specifics</p>
}

{
"id": "3131a",

"domain": "https://cernel.shop.dk",

"site_id": 0,

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",
"name": "SAGA Baristamaskine (Sort)",
"language": "Danish",
"short_description": "<p>Short description</p>",
"description": "<p>Long description</p>",
"meta_title": "Meta title content",
"meta_description": "Meta description content",
"alt_text": "Alt text content",
"status": "SUCCESS",
"report": <h2>Product generation Report</h2>

<p>Generation specifics</p>
}

Update Product

Query parameters

(Optional: localization) Localization is enabled through the localization parameter. Localization sites in the payload is ignored otherwise.


(Optional: template_id) Templates are passed as arguments through their ID. The configured template will be fetched from the platform. Defaults to Cernel Base Template.

Request body

Include a list of products with data to queue generations for a specific site. Each product requires fields "name" and "external_id". To improve the quality of generations as much relevant data as possible should be included in the payload. "gtin" field might be required in some cases for localization to work properly across sites.

Response body

The request returns the state of the queued job and the corresponding UUID4 job id that is a global and unique identifier used to fetch resource

Webhooks

Webhooks can be configured through the platform. Upon job completion the webhook returns data to the webhook URL.

Endpoint

POST

/products/update

Query parameters

Payload:

?template_id={0,1,…}
?localize={true,false}

Request samples

application/json

application/json

{

"products": [

{

"brand": "Yeti",

"name": "Bluetooth Høretelefoner - Sort",

"language": "Danish",

"gtin": "4752223017759",

"external_id": "4752223017759",

"price": 435.00,

"description": "Bluetooth høretelefoner i sort fra Yeti. Op til

14 timers batteri-levetid. Case med USB-C opladning.",

"attributes": {

"battery_life_h": "14",

"country_origin": "CHINA",

"weight": "145g",

"closure": "Snap Lock Magnetic",

"color": "Black / Mátte Black",

},

"images": []

}

],

"localizations": {

"domains": [{"url": "https://www.cernel.de", "site_id": 0}],

"filter_by": "gtin"

},

"domain": "https://www.cernel.shop",

"site_id": 0

}

{
"domain": "https://cernel.shop.dk
"categories": [
{
"number": "https://cernel.shop.dk/produkter/…"
},
{
"number": "https://cernel.shop.dk/produkter/…""
}
]
}

Response samples

Status 202:

application/json

application/json

{
"status": "queued"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

{
"status": "queued"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

Status 4xx:

application/json

application/json

{
"status": "failure"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

{
"status": "failure"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

Webhook

application/json

application/json

{

"id": "3303170120804",

"domain": "https://cernel.shop.dk",

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",

"site_id": 0,

"name": "Bluetooth Høretelefoner - Sort",

"language": "Danish",

"short_description": "Generated short description",

"description": "Generated description",

"meta_title": "Generated meta title",

"meta_description": "Generated meta description",

"alt_text": "Generated alt text",

"status": "SUCCESS",

"report": null

}

Category Updates

Request body

Cernel uses identifiers to generate categories, which allows for updates through the API.

Response body

The request returns the state of the queued job and the corresponding UUID4 job id that is a global and unique identifier used to fetch resource

Webhooks

Webhooks can be configured through the platform. Upon job completion the webhook returns data to the webhook URL.

Endpoint

POST

/categories

Request samples

Payload:

application/json

application/json

{
"domain": "https://cernel.shop.dk,

"site_id": 0,
"categories": [
{
"number": "kaffemaskiner-124a"
},
{
"number": "rens-og-pleje-1c91"
}
]
}

{
"domain": "https://cernel.shop.dk
"categories": [
{
"number": "https://cernel.shop.dk/produkter/…"
},
{
"number": "https://cernel.shop.dk/produkter/…""
}
]
}

Response samples

Status 202:

application/json

application/json

{
"status": "queued"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

{
"status": "queued"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

Status 4xx:

application/json

application/json

{
"status": "failure"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

{
"status": "failure"
"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f"
}

Webhook

application/json

application/json


{
"id": "3131a",

"domain": "https://cernel.shop.dk",

"site_id": 0,

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",
"name": "Kaffemaskiner",
"language": "Danish",
"short_description": "<p>Short description</p>",
"description": "<p>Long description</p>",
"meta_title": "Meta title content",
"meta_description": "Meta description content",
"alt_text": "Alt text content",
"status": "SUCCESS",
"report": <h2>Category generation Report</h2>

<p>Generation specifics</p>
}


{
"id": "3131a",

"domain": "https://cernel.shop.dk",

"site_id": 0,

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",
"name": "Kaffemaskiner",
"language": "Danish",
"short_description": "<p>Short description</p>",
"description": "<p>Long description</p>",
"meta_title": "Meta title content",
"meta_description": "Meta description content",
"alt_text": "Alt text content",
"status": "SUCCESS",
"report": <h2>Category generation Report</h2>

<p>Generation specifics</p>
}

Job results

Request body

The generated content can be fetched through the unique job UUID.

Response body

Returns all generation data from the job.

Endpoint

GET

/jobs/<str:job_id>

Response samples

Status 200:

application/json

application/json

[

{

"id": "3303170120804",

"name": "Bluetooth Høretelefoner - Sort",

"language": "Danish",

"short_description": "Generated short description",

"description": "Generated description",

"meta_title": "Generated meta title",

"meta_description": "Generated meta description",

"alt_text": "Generated alt text",

"status": "SUCCESS",

"report": null

},

{

"id": "3303170120804",

"name": "Bluetooth Høretelefoner - Sort",

"language": "Norwegian",

"short_description": "Generated short description",

"description": "Generated description",

"meta_title": "Generated meta title",

"meta_description": "Generated meta description",

"alt_text": "Generated alt text",

"status": "SUCCESS",

"report": null

}

]

All jobs

Response body

The request returns all jobs for all sites associated with the API token.

Endpoint

GET

/jobs

?page={0,1,…}

?per_page={0,1,…}

Response samples

Status 200:

application/json

application/json

{

"page": 1,

"per_page": 50,

"page_count": 3,

"total": 125,

"results": [

{

"created_at": "2024-03-20T15:30:45",

"user": "john.doe@example.com",

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",

"job_state": "SUCCESS",

"products": [{"number": "rbcs-12", "name": "Rolf Benz Corner Sofa"}],

"categories": [{"number": "sf-12", "name": "Sofas"}],

"token_cost": 30,

"token_refund": 0,

"failed_product_count": 0,

"failed_category_count": 0

},

{

"created_at": "2024-03-20T15:25:30",

"user": "John Doe",

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",

"job_state": "PARTIAL_SUCCESS",

"products": [

{"number": "rbcs-12", "name": "Rolf Benz Corner Sofa"},

{"number": "rbcs-13", "name": "Rolf Benz Corner Sofa Small"},

{"number": "rbcs-14", "name": "Rolf Benz Corner Sofa Medium"}

],

"categories": [],

"token_cost": 3,

"token_refund": 1,

"failed_product_count": 1,

"failed_category_count": 0

},

{

"created_at": "2024-03-20T15:20:00",

"user": "jane.smith@example.com",

"job_state": "FAILURE",

"job_id": "163f99d4-e53f-4d07-9051-97d298c7306f",

"products": [],

"categories": [

{"number": "sf-12", "name": "Sofas"},

{"number": "oc-12", "name": "Office Chairs"}

],

"token_cost": 8,

"token_refund": 8,

"failed_product_count": 0,

"failed_category_count": 2

}

]

}

Sites

Response body

The request returns all sites associated with the API token.

Endpoint

GET

/sites

Response samples

Status 200:

application/json

application/json

[

{

"id": 543,

"domain": "https://shop.cernel.dk",

"language": "Danish",

"name": "Cernel Shop (Danish)",

"type": "Shopify",

"site_id": 0,

"initial_keyword_count": 0,

"keyword_increase": 0,

"exclude_from_statistics": false

},

{

"id": 649,

"domain": "https://shop.cernel.de",

"language": "German",

"name": "Cernel Shop (German)",

"type": "Shopify",

"site_id": 0,

"initial_keyword_count": 0,

"keyword_increase": 0,

"exclude_from_statistics": false

}

]

Templates

Response body

The request returns all templates for the organization associated with the API token.

Endpoint

GET

/templates

Response samples

Status 200:

application/json

application/json

[{

"id": 128,

"name": "Template - Default",

"description": "Created By Cernel. A good starting point to see our product

agent in action.",

"master_prompt": "Focus on the numerical details.\nExplain what the

specifications mean for the user, and address pain points.\n\nAvoid using

technical jargon.\nAvoid using superlative words, like 'optimal', 'best',

'most', 'perfect', 'ultimate', etc.\nAvoid using excessive adjectives,

like 'elegant', 'timeless','fantastic', etc.\nAvoid common AI phrase

structures, like 'not just X,it is Y...', 'X meets Y...'. \nAvoid words

that AIs commonly overuse,such as 'timeless', 'elegance', 'comfort meets

style', 'ultimate' etc. \n\nWrite directly to the consumer.",


"tov": "Keep the copy short and informative. Stay clear of excessive

appraisals and superlatives. Authentic, approachable and

benefit-oriented.",

"tov_reference": "",

"layout": [

{

"type": "h2",

"length": 5,

"prompt": "Use the name of the product as the title of

this section.",

"examples": [],

"referral_name": ""

},

{

"type": "p",

"length": 40,

"prompt": "",

"examples": [],

"referral_name": ""

},

{

"type": "h3",

"length": 5,

"prompt": "",

"examples": [

"Fit for any home",

"A companion for every journey"

],

"referral_name": ""

},

{

"type": "ul",

"length": 0,

"prompt": "",

"examples": [],

"bulletCount": 3,

"referral_name": "",

"wordsPrBullet": 8

},

{

"type": "h3",

"length": 5,

"prompt": "",

"examples": [

"Exclusive finish with seamless design",

"Options that match your personal needs"

],

"referral_name": ""

},

{

"type": "p",

"length": 50,

"prompt": "Write a few sentences about the product's features.",

"examples": [],

"referral_name": ""

},

{

"type": "h3",

"length": 5,

"prompt": "",

"examples": [

"Design that fits your style",

"A proper tool"

],

"referral_name": ""

},

{

"type": "p",

"length": 50,

"prompt": "Write a few sentences about the product's benefits.",

"examples": [],

"referral_name": ""

},

{

"type": "pl",

"length": 10,

"prompt": "",

"examples": [],

"referral_name": ""

}

],

"dynamic_add_ul_tags": 3,

"dynamic_add_p_tags": 1,

"dynamic_p_tag_header": "h3",

"run_intent_analysis": true,

"user_input_eval": true,

"factfullness_eval": false,

"data_representation_eval": false,

"layout_eval": true

}]