REST API
Az Askalot REST API-t kínál a platform összes képességének programozott eléréséhez. Az API-val automatizálhatja a kérdőíves munkafolyamatokat, külső rendszerekkel integrálhatja a platformot, és saját alkalmazásokat építhet az Askalotra.
Első lépések
Szekció neve “Első lépések”Alap-URL
Szekció neve “Alap-URL”https://portor.<tenant>.askalot.io/api/v1A <tenant> helyére a szervezete bérlőjének nevét írja (például portor.acme.askalot.io).
Hitelesítés
Szekció neve “Hitelesítés”Minden API-kérést személyes API-tokennel kell hitelesíteni.
Token létrehozása:
- Jelentkezzen be a
https://roundtable.<tenant>.askalot.iocímen - Lépjen a Profilbeállítások oldalra
- Görgessen az „API-tokenek” szakaszhoz
- Kattintson az „Új token létrehozása” gombra
- Másolja ki a tokent (csak egyszer jelenik meg)
A token használata:
Küldje a tokent az X-Api-Token fejlécben:
curl -H "X-Api-Token: your_token_here" \ https://portor.<tenant>.askalot.io/api/v1/projectsA token tulajdonságai:
- Formátum: a tokenek
aslat_előtaggal kezdődnek (aslat_<32 characters>); az előtag alapján a titokkereső eszközök kiszúrhatják a véletlenül verziókezelőbe került tokent. A szerver azonosítás céljából csak az előtagot tárolja – a teljes token csak egyszer, a létrehozáskor jelenik meg, és soha többé. - Fejléc: az
X-Api-Tokenfejlécben küldje. Ez a REST hitelesítési módja; a PortorAuthorization: Bearerfejléce az OAuth-hozzáférési tokeneknek van fenntartva (azoknak, amelyeket egy MCP-munkamenet hordoz, és amelyeket a REST is elfogad), nem az API-tokeneknek. - Hatókör: csak a REST API-t hitelesíti, az MCP-felület nem fogadja el. A token ahhoz a szervezethez tartozik, amelyben Ön a token létrehozásakor dolgozott: minden kérése abban a szervezetben fut, az ott betöltött szerepköreivel – a más szervezetben betöltött szerepkör nem érvényes. Ha REST-en keresztül egy másik szervezetben szeretne dolgozni, váltson át oda a böngészőben, és ott hozzon létre tokent. Ha egy adminisztrátor eltávolítja Önt abból a szervezetből, a rendszer a tagsággal együtt az ottani tokenjeit is visszavonja.
- Visszavonás: bármikor visszavonhatja a Profilbeállításokban; a visszavonás azonnal érvénybe lép.
A token élettartama és cseréje
Szekció neve “A token élettartama és cseréje”A token létrehozásakor Ön választja meg a lejáratot – a Profilbeállítások legördülő listája 30 nap, 90 nap (az alapértelmezés) és 1 év lehetőséget kínál. A lejárat megadása kötelező; az új tokenekhez nincs „soha le nem járó” lehetőség (csak a régebbi, korábbi szabályok szerint létrehozott tokeneknek hiányozhat a lejárata).
- A Profilbeállítások minden tokennél megmutatja a lejárat dátumát és a hátralévő napok számát, és cserére jelöli a tokent, ha a lejáratáig 14 napnál kevesebb van hátra.
- A csere menete: hozzon létre egy helyettesítő tokent, állítsa át rá az integrációját, majd vonja vissza a régit. A tokenek nem újulnak meg automatikusan – a lejárt token
401választ kap, és le kell cserélni.
Interaktív dokumentáció
Szekció neve “Interaktív dokumentáció”Az API-t interaktívan a Swagger UI-ban fedezheti fel:
https://portor.<tenant>.askalot.io/api/v1/docsAz interaktív dokumentációban:
- böngészheti az összes elérhető végpontot,
- megtekintheti a kérések és válaszok sémáit,
- közvetlenül a böngészőből kipróbálhatja az API-hívásokat.
Alapvető erőforrások
Szekció neve “Alapvető erőforrások”Projektek
Szekció neve “Projektek”A projektek a kérdőíves kutatás szervezésére szolgáló legfelső szintű tárolók.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/projects |
Az összes projekt listázása |
POST |
/api/v1/projects |
Új projekt létrehozása |
GET |
/api/v1/projects/{id} |
Projekt lekérése azonosító alapján |
PUT |
/api/v1/projects/{id} |
Projekt módosítása |
DELETE |
/api/v1/projects/{id} |
Projekt törlése |
POST |
/api/v1/projects/{id}/owners |
Projekttulajdonosok felvétele |
DELETE |
/api/v1/projects/{id}/owners |
Projekttulajdonosok eltávolítása |
Példa: projekt létrehozása
curl -X POST https://portor.<tenant>.askalot.io/api/v1/projects \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Satisfaction Study", "description": "Q1 2026 customer feedback survey" }'Válasz:
{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Customer Satisfaction Study", "description": "Q1 2026 customer feedback survey", "created_at": "2026-01-02T10:30:00Z", "questionnaire_ids": [], "campaign_ids": []}Kérdőívek
Szekció neve “Kérdőívek”A kérdőív szerkezetét a QML (Questionnaire Markup Language) írja le.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/questionnaires |
Az összes kérdőív listázása |
POST |
/api/v1/questionnaires |
Új kérdőív létrehozása |
GET |
/api/v1/questionnaires/{id} |
Kérdőív lekérése azonosító alapján |
PUT |
/api/v1/questionnaires/{id} |
Kérdőív módosítása |
DELETE |
/api/v1/questionnaires/{id} |
Kérdőív törlése |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations |
Egy verzió fordításainak listázása nyelvenként (teljes-e, lefordítatlan kulcsok, befagyasztott, ember által szerkesztett) |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Egy nyelv fordításának lekérése a forrásszövegeivel együtt |
PUT |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Lefordított szöveg mentése (texts, base_updated_at); részleges, a tárolt fordítással összefésülve |
DELETE |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Egy nyelv fordításának törlése (befagyasztás után elutasítva) |
Lekérdezési paraméterek:
project_id– szűrés projekt szerintstatus– szűrés állapot szerint (draft,active,paused,completed)
Kampányok
Szekció neve “Kampányok”A kampányok az adatgyűjtéshez kapcsolják össze a kérdőíveket a válaszadókkal.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/campaigns |
Az összes kampány listázása |
POST |
/api/v1/campaigns |
Új kampány létrehozása |
GET |
/api/v1/campaigns/{id} |
Kampány lekérése azonosító alapján |
PUT |
/api/v1/campaigns/{id} |
Kampány módosítása |
DELETE |
/api/v1/campaigns/{id} |
Kampány törlése |
PUT |
/api/v1/campaigns/{id}/pool |
Válaszadói kör hozzárendelése a kampányhoz |
GET |
/api/v1/campaigns/{id}/pool |
A kampányhoz rendelt válaszadói kör lekérése |
PUT |
/api/v1/campaigns/{id}/questionnaire |
A kampány kérdőívének módosítása |
POST |
/api/v1/campaigns/{id}/interviewers |
Kérdezők felvétele a kampányba |
DELETE |
/api/v1/campaigns/{id}/interviewers |
Kérdezők eltávolítása a kampányból |
Lekérdezési paraméterek:
project_id– szűrés projekt szerintquestionnaire_id– szűrés kérdőív szerintstatus– szűrés állapot szerintexpand=true– a kapcsolódó objektumok (projekt, kérdőív, válaszadók) beemelése
Kampány létrehozása: a POST /api/v1/campaigns kéréshez kötelező a name, a project_id, a questionnaire_id és az offers_ai_channel. Az offers_ai_channel (logikai érték) azt adja meg, hogy a válaszadók a saját MI-asszisztensükben is kitölthetik-e a kérdőívet. Nincs alapértéke, és a nélküle küldött kérést a rendszer elutasítja. Ha true, az intro_text és a consent_text is kötelező. Lásd: MI-asszisztált önkitöltés.
Kampánymódok:
Az Askalot kétféle kampánymódot támogat:
- Közvetlen mód: a válaszadók egyedi linkeken keresztül, önállóan töltik ki a kérdőíveket
- Kérdezős mód: a kérdezők telefonon vagy személyesen veszik fel a kérdőívet a válaszadókkal
A mód automatikusan dől el aszerint, hogy rendeltek-e kérdezőket a kampányhoz.
Minden kitöltés a saját módját is rögzíti (direct, ai_assisted vagy field_interview) a mode mezőjében. Egy kitöltés akkor ai_assisted, ha a kampány felkínálja az MI-asszisztenst, és a válaszadó a válaszadás előtt ott adta meg a beleegyezését.
Válaszadók
Szekció neve “Válaszadók”A válaszadók a kérdőívek célszemélyei – azok az emberek, akiket megkérdeznek.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/respondents |
Az összes válaszadó listázása |
POST |
/api/v1/respondents |
Új válaszadó létrehozása |
GET |
/api/v1/respondents/{id} |
Válaszadó lekérése azonosító alapján |
PUT |
/api/v1/respondents/{id} |
Válaszadó módosítása |
DELETE |
/api/v1/respondents/{id} |
Válaszadó törlése |
Lekérdezési paraméterek:
source_system– szűrés forrás szerint (példáulcrm,panel_provider)campaign_id– szűrés kampány szerint
Megjegyzés: A kérdezők interviewer szerepkörű felhasználók. Őket az /api/v1/users végponton keresztül kezelheti.
Példa: válaszadó importálása
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Smith", "email": "[email protected]", "age": 35, "gender": "female", "location": "New York", "external_id": "CRM-12345", "source_system": "salesforce", "custom_attributes": {"state": "NY", "zip_code": "10001"} }'Demográfiai mezők:
A válaszadókhoz demográfiai adatok tárolhatók a célzáshoz és az elemzéshez:
age– a válaszadó életkoragender– nemi identitáslocation– földrajzi hely (szabad szöveg, jellemzően"City, Country"formában)external_id– az Ön rendszerének azonosítójasource_system– a válaszadói adatok forrásapreferred_language– opcionális preferált nyelv (en,es,fr,de,hu); ezen a nyelven készül a meghívó, és ez lesz a kérdőív előre kiválasztott nyelve, ha a kampány kínálja
A location mezőnél finomabb földrajzi adat – utca, város, állam, irányítószám, ország külön értékként – a custom_attributes mezőbe kerül, és mindenhol custom_attributes.<key> formában hivatkozható, ahol válaszadói attribútum megnevezhető (mintavételi tényezők, külső bemeneti leképezések). A kalibrációs célérték azt az adatkészlet-oszlopot nevezi meg, amelybe az attribútumot kinyerték: _custom_<key>. A további felső szintű kulcsokat a rendszer nem tárolja, hanem figyelmen kívül hagyja, így egy olyan CRM-export, amely a city értéket külön mezőként küldi, ezt az értéket észrevétlenül elveszíti.
Kitöltések
Szekció neve “Kitöltések”A kitöltések az egyes kérdőív-kitöltési munkameneteket és a válaszokat követik nyomon.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/surveys |
Az összes kitöltés listázása |
POST |
/api/v1/surveys |
Új kitöltési munkamenet létrehozása |
GET |
/api/v1/surveys/{id} |
Kitöltés lekérése azonosító alapján |
PUT |
/api/v1/surveys/{id} |
Kitöltés állapotának módosítása |
DELETE |
/api/v1/surveys/{id} |
Kitöltés törlése |
GET |
/api/v1/surveys/{id}/current-step |
Az aktuális kérdés + válaszlehetőségek + állapot (A kérdőív megjelenítési formátuma) |
POST |
/api/v1/surveys/{id}/responses |
Válasz beküldése; a következő lépés a válaszban érkezik |
POST |
/api/v1/surveys/{id}/finish |
A kitöltés kifejezett lezárása (idempotens) |
Lekérdezési paraméterek:
questionnaire_id– szűrés kérdőív szerintcampaign_id– szűrés kampány szerintrespondent_id– szűrés válaszadó szerintstatus– szűrés állapot szerint (pending,in_progress,completed)expand=true– a kapcsolódó objektumok beemelése
A kitöltésekről adott API-válaszok a status mellett egy származtatott, írásvédett completed logikai értéket is tartalmaznak (pontosan akkor true, ha a status értéke completed). A befejezést a status módosítása fejezi ki – nincs completed bemeneti vagy szűrőparaméter.
A kérdőív kitöltése a POST /api/v1/surveys/{id}/responses végponton keresztül tesztelésre és szimulációra korlátozódik: azt a kitöltést, amelyhez már meghívót küldtek, a rendszer elutasítja, így egy élő terepmunka-interjúba programozottan nem lehet írni. Az így beküldött válaszokat a rendszer gépi előállításúként rögzíti, és a válaszidejük kimarad a túl gyors kitöltők észleléséből.
Válaszadói körök
Szekció neve “Válaszadói körök”A válaszadói körök a válaszadókat több kampányban is felhasználható csoportokba rendezik.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/respondent-pools |
Az összes válaszadói kör listázása |
POST |
/api/v1/respondent-pools |
Új válaszadói kör létrehozása |
GET |
/api/v1/respondent-pools/{id} |
Válaszadói kör lekérése azonosító alapján |
DELETE |
/api/v1/respondent-pools/{id} |
Válaszadói kör törlése |
POST |
/api/v1/respondent-pools/{id}/respondents |
Válaszadók felvétele a válaszadói körbe |
DELETE |
/api/v1/respondent-pools/{id}/respondents |
Válaszadók eltávolítása a válaszadói körből |
POST |
/api/v1/respondent-pools/generate |
Válaszadói kör húzása egy mintavételi stratégiából (a requested_size kötelező); a válaszadói kör eltárolja a húzás beállításait |
POST |
/api/v1/respondent-pools/preview |
Egy húzás előnézete válaszadói kör létrehozása nélkül |
POST |
/api/v1/respondent-pools/{id}/refresh |
Egy stratégiából húzott válaszadói kör újrahúzása a saját tárolt húzási beállításaival |
Lekérdezési paraméterek:
project_id– szűrés projekt szerint
Mintavételi stratégiák
Szekció neve “Mintavételi stratégiák”A mintavételi stratégiák a reprezentatív minták létrehozásához szükséges demográfiai célmegoszlásokat határozzák meg, valamint azt, hogyan kell értékelni az ezekhez való illeszkedést. A stratégia nem tartalmaz méretet vagy kiválasztási beállítást: ezek a POST /api/v1/respondent-pools/generate bemenetei, és a rendszer az így létrehozott válaszadói körrel együtt tárolja őket.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/sampling-strategies |
Az összes stratégia listázása |
POST |
/api/v1/sampling-strategies |
Új stratégia létrehozása |
GET |
/api/v1/sampling-strategies/{id} |
Stratégia lekérése azonosító alapján |
PUT |
/api/v1/sampling-strategies/{id} |
Stratégia módosítása |
DELETE |
/api/v1/sampling-strategies/{id} |
Stratégia törlése |
Lekérdezési paraméterek:
project_id– szűrés projekt szerint
Példa: mintavételi stratégia létrehozása
curl -X POST https://portor.<tenant>.askalot.io/api/v1/sampling-strategies \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Representative Sample", "project_id": "550e8400-e29b-41d4-a716-446655440000", "factors": [ { "name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02} }, { "name": "Age Group", "attribute_path": "age", "factor_type": "bucketed", "target_distribution": {"18-34": 0.35, "35-54": 0.40, "55+": 0.25} } ] }'Példa: válaszadói kör húzása a stratégiából
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondent-pools/generate \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "strategy_id": "<strategy id>", "pool_name": "Pilot wave", "requested_size": 100, "oversample_factor": 1.2 }'A requested_size kötelező; az oversample_factor (alapértelmezés: 1.0), a selection_algorithm (greedy vagy random_constrained, alapértelmezés: greedy), a require_email (alapértelmezés: false) és az exclude_respondent_ids (alapértelmezés: nincs) opcionális. Ha szüksége van rá, ugyanabból a stratégiából bármikor húzhat egy második, eltérő méretű válaszadói kört is.
Csomagok
Szekció neve “Csomagok”A csomag egy projektet → egy kérdőívet → a kampányok kiválasztott részhalmazát köti egyetlen lineáris Bronz → Ezüst → Arany adatkészlet-lánchoz – ez az az egység, amely köré a Balansor adatfolyam-táblája szerveződik.
| Metódus | Végpont | Leírás |
|---|---|---|
GET |
/api/v1/bundles |
Az összes csomag listázása |
POST |
/api/v1/bundles |
Új csomag létrehozása |
GET |
/api/v1/bundles/{id} |
Csomag részletei, a fázisreceptekkel együtt (Ezüst kalibrációs célértékek, Arany műveletek) |
DELETE |
/api/v1/bundles/{id} |
Csomag törlése (az adatkészlet-láncával együtt) |
POST |
/api/v1/bundles/{id}/clone |
Csomag klónozása – mély másolat: a kész adatkészletek és a fázisreceptek is átkerülnek |
GET |
/api/v1/bundles/{id}/quality |
A csomag reprezentativitásának alakulása (kiválasztás, terepen megvalósult, súlyozott, terepmunka-eltolódás, válaszadás) |
GET |
/api/v1/bundles/{id}/comparison |
A Bronz és az Ezüst adatkészlet összehasonlítása (409 conflict, amíg mindkét fázis nem ready) |
GET |
/api/v1/bundles/{id}/coding |
A nyitott válaszok kódolásának állapota – a Bronz adatkészlet által kínált kódolási jelöltek, az elemző kérdésválasztása, valamint kérdésenként a javasolt dimenziók a kategóriáikkal és a kiválasztásuk állapotával (hogy mely dimenziókból lesznek oszlopok, azt továbbra is a Balansor felületén kell eldönteni) |
PUT |
/api/v1/bundles/{id}/coding/selection |
Annak beállítása, mely nyitott szöveges egységeket kódolja ez a csomag – az egységkulcsok teljes halmaza, amely felváltja a korábbit (menedzser szerepkör, azonosított felhasználó szükséges) |
POST |
/api/v1/bundles/{id}/strategy |
A csomag aktuális mintavételi stratégiájának hozzárendelése vagy törlése (menedzser szerepkör, azonosított felhasználó szükséges) |
PUT |
/api/v1/bundles/{id}/targets |
A csomag kalibrációs célértékeinek szerkesztése – ez az Ezüst adatkészlet súlyozási specifikációja, mindegyik célérték raked vagy benchmark (menedzser szerepkör, azonosított felhasználó szükséges) |
GET |
/api/v1/bundles/{id}/targets/copy-preview?source_bundle_id={source} |
Egy másik csomag kalibrációs célértékeinek erre a csomagra való másolásának előnézete: addable és rejected, indoklással; semmit sem ír (menedzser szerepkör) |
Lekérdezési paraméterek:
project_id– szűrés projekt szerint
A fázisműveleteket (kinyerés, kódolás + súlyozás, finomítás, export) az MCP csomag- és adatkészlet-eszközei vezérlik – a teljes minőségi és fázisparaméter-referenciát lásd az mcp-bundle-tools.md és az mcp-dataset-tools.md oldalon.
Válaszformátum
Szekció neve “Válaszformátum”Sikeres válaszok
Szekció neve “Sikeres válaszok”Minden sikeres válasz JSON formátumú, szabványos HTTP-állapotkóddal:
| Állapot | Jelentés |
|---|---|
200 OK |
A kérés sikeres volt (az erőforrás létrehozását is beleértve – a létrehozott objektum a válasz törzsében érkezik) |
204 No Content |
Az erőforrás törlése sikeres volt |
Hibaválaszok
Szekció neve “Hibaválaszok”A hibák egységes borítékot használnak: egy géppel olvasható error kódot és egy ember számára olvasható detail leírást:
{ "error": "not_found", "detail": "bundle 'abc123' not found"}| Állapot | error kód |
Jelentés |
|---|---|---|
401 |
unauthenticated |
Hiányzó, érvénytelen vagy lejárt hitelesítő adat |
403 |
forbidden |
Nincs meg a szükséges képessége, vagy nem Ön a célerőforrás tulajdonosa |
404 |
not_found |
Az erőforrás nem létezik (vagy Ön nem láthatja) |
409 |
conflict |
A kérés érvényes, de az erőforrás még nem áll készen (például olyan csomag összehasonlítása, amelynek a lánca még feldolgozás alatt áll) – próbálja újra, miután az adatfolyam befejeződött |
422 |
validation_error |
Hibás bemenet; a detail mezőnkénti hibák listáját tartalmazza |
OpenAPI-specifikáció
Szekció neve “OpenAPI-specifikáció”A teljes API-specifikáció OpenAPI 3.0 formátumban érhető el:
GET /api/v1/openapi.jsonEbből a specifikációból típusos API-klienseket generálhat a kívánt programozási nyelven.
Gyakori munkafolyamatok
Szekció neve “Gyakori munkafolyamatok”Kampánylétrehozás automatizálása
Szekció neve “Kampánylétrehozás automatizálása”# 1. Create a projectPROJECT_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/projects \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Q1 Survey"}' | jq -r '.id')
# 2. Create a questionnaire (the QML itself is the payload — there is no file to stage)QUESTIONNAIRE_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/questionnaires \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg p "$PROJECT_ID" --rawfile c feedback.qml \ '{name: "Customer Feedback", project_id: $p, content: $c}')" | jq -r '.id')
# 3. Create a campaigncurl -X POST https://portor.<tenant>.askalot.io/api/v1/campaigns \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "{\"name\": \"Q1 Campaign\", \"project_id\": \"$PROJECT_ID\", \"questionnaire_id\": \"$QUESTIONNAIRE_ID\", \"offers_ai_channel\": false}"Válaszadók importálása a CRM-rendszeréből
Szekció neve “Válaszadók importálása a CRM-rendszeréből”# Import respondents from a CSV or your CRM systemfor respondent in "${RESPONDENTS[@]}"; do curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "$respondent"done