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:
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:
Response samples
Status 202:
Status 4xx:
Webhook
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
Response samples
Status 202:
Status 4xx:
Webhook
{
"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:
Response samples
Status 202:
Status 4xx:
Webhook
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:
[
{
"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:
{
"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:
[
{
"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:
[{
"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
}]