Queries

Endpoints

POST/v1/brands/{brand}/queries
PATCH/v1/brands/{brand}/queries/{query}
GET/v1/brands/{brand}/queries/{query}
GET/v1/brands/{brand}/queries

L’objet Query

Attributs

idstring
Identifiant unique de l'objet (préfixé, opaque).
objectstring
query
textstring
marketstring
Code du marché (pays ISO, par ex. FR).
categorystringnullable
intentenum
The shopping-query templates of the spec: « meilleur X », « X vs Z », « alternatives à X ». Detected on manual prompts, explicit on generated ones; anything else is custom.
Valeurs possibles : best_x · x_vs_z · alternatives_to_x · custom
sourceenum
| | |---| | generated <br/> Generated from the catalog at onboarding / re-generation. | | manual <br/> Added by hand in the prompt panel. |
Valeurs possibles : generated · manual
enabledboolean
visibilityobject
Share (%) of the answers citing the brand over the period — null before any measurement.
livemodeboolean
true pour les données réelles, false pour le bac à sable du mode test.
createdinteger
Time at which the object was created (unix timestamp, seconds).

L'objet Query


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

Create a query

POST/v1/brands/{brand}/queries

Adds a query to the panel of an activated market, enabled: it is asked from the next weekly sampling on. A duplicate on the market, or a full quota (quota_exceeded), answers 422.

Paramètres

brandstringobligatoire
Brand id (br_…).
textstringobligatoire
marketstringobligatoire
An activated market of the brand (ISO 3166-1 alpha-2).
categorystringnullable

Retour

Renvoie l’objet query créé. Lève une erreur en cas de problème.

curl


curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"text":"meilleur vélo gravel carbone à moins de 3000 €","market":"FR","category":"string"}'

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"text":"meilleur vélo gravel carbone à moins de 3000 €","market":"FR","category":"string"}),
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('POST', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
    'json' => ['text' => 'meilleur vélo gravel carbone à moins de 3000 €', 'market' => 'FR', 'category' => 'string'],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.post(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
    json={"text": "meilleur vélo gravel carbone à moins de 3000 €", "market": "FR", "category": "string"},
)
data = response.json()

Réponse


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

Update a query

PATCH/v1/brands/{brand}/queries/{query}

Edits the text or the category, or enables / disables the query. Disabling frees a slot of the quota; enabling takes one.

Paramètres

brandstringobligatoire
Brand id (br_…).
querystringobligatoire
Query id (qry_…).
textstring
categorystringnullable
enabledboolean

Retour

Renvoie l’objet query mis à jour. Lève une erreur en cas de problème.

curl


curl -X PATCH https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"text":"meilleur vélo gravel carbone à moins de 3000 €","category":"string"}'

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"text":"meilleur vélo gravel carbone à moins de 3000 €","category":"string"}),
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('PATCH', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
    'json' => ['text' => 'meilleur vélo gravel carbone à moins de 3000 €', 'category' => 'string'],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.patch(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
    json={"text": "meilleur vélo gravel carbone à moins de 3000 €", "category": "string"},
)
data = response.json()

Réponse


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

Retrieve a query

GET/v1/brands/{brand}/queries/{query}

Paramètres

brandstringobligatoire
Brand id (br_…).
querystringobligatoire
Query id (qry_…).

Retour

Renvoie l’objet query. Lève une erreur en cas de problème.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Réponse


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

List queries

GET/v1/brands/{brand}/queries

The queries of the brand’s panel — the questions asked to the AI models every week — with the share of the answers citing the brand over the period.

Paramètres

brandstringobligatoire
Brand id (br_…).
marketstring
enabledstring
limitinteger
Nombre d'objets à renvoyer, entre 1 et 100 (20 par défaut).
starting_afterstring
Curseur : l'id du dernier objet de la page précédente.

Retour

Un dictionnaire dont la propriété data contient jusqu’à limit objets query, du plus récent au plus ancien, et has_more indique s’il reste une page. Lève une erreur en cas de problème.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Réponse


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries",
  "has_more": false,
  "data": [
    {
      "id": "qry_034ONPxljEmTTql8cv7qJk",
      "object": "query",
      "text": "meilleur vélo gravel carbone à moins de 3000 €",
      "market": "FR",
      "category": "string",
      "intent": "best_x",
      "source": "generated",
      "enabled": true,
      "visibility": {},
      "livemode": true,
      "created": 1790000000
    }
  ]
}