Knowledge Base API #

Tietokantasi on se, mistä tekoäly lukee tiedot. Se koostuu kahdesta osasta, ja tämä sivu käsittelee molempia:

• Tietolähteet (/kb-sources) — verkkosivut ja ladatut asiakirjat, joita syötät alustalle. Jokainen niistä luetaan, jaetaan osiin ja muutetaan UKK-kysymyksiksi, joihin tekoälysi voi vastata.
• Tietoryhmät (/kb-groups) — UKK-kysymysten nimetyt niput, joita voit käyttää agentille tai kampanjalle yhdellä kutsulla, jolloin jo kuratoimasi tietopohja voidaan käyttää uudelleen seuraavassa luomassasi agentissa.

Lähteen tuottamat UKK-kysymykset päätyvät samaan kirjastoon kuin käsin kirjoittamasi, joten kun tuonti on valmis, voit lukea, muokata ja linkittää niitä UKK-rajapinnan avulla.

Kaikki alla olevat päätepisteet ovat suhteessa perus-URL-osoitteeseen https://api.youraiconnector.com/v1. Jokainen pyyntö on todennettava – katso API-käyttöoikeus ja Todennus. API-käyttöoikeus on maksullinen ominaisuus; ilman sitä pyynnöt hylätään virheellä 403.

Tuonti kuluttaa krediittejä. Sivun tai asiakirjan lukeminen ja siitä UKK-kysymysten kirjoittaminen kuluttaa krediittejä suunnilleen sisällön määrän mukaan. Käytä Tuonnin arviointia ennen kuin aloitat laajan indeksoinnin.

Miten tuonti toimii #

Tuonti on taustaprosessi, ei toiminto, joka valmistuu odottaessasi. Jokainen tuonnin päätepiste vastaa välittömästi source_id-tunnisteella, ja voit kysellä lähteen tilaa, kunnes se on valmis:

1. Aloita tuonti — POST /kb-sources/url (yksi sivu), POST /kb-sources/file (ladattu asiakirja) tai POST /kb-sources/bulk-import (jopa 100 sivua). Saat takaisin lähteen tunnisteen ja status: "queued"-tunnisteen.
2. Kysely — GET /kb-sources/{sourceId} kunnes status ei ole enää queued tai processing.
3. Lue UKK-kysymykset — kun tila on ready, sen tuottamat merkinnät ovat UKK-kirjastossasi: GET /faqs.

Jokainen lähde raportoi yhden seuraavista tiloista:

Liitä tuonnin yhteydessä. Välitä autoLinkToAgentId missä tahansa tuonnin päätepisteessä, niin lähde — sekä jokainen sen tuottama UKK-kysymys — päätyy kyseisen agentin tietokantaan samalla kutsulla ilman erillistä linkitysvaihetta. autoLinkToCampaignId tekee saman klassiselle kampanjalle. Linkitys on parhaan yrityksen periaate: tunniste, jota ei ole olemassa tai joka kuuluu toiselle tilille, ohitetaan hiljaisesti ja tuonti jatkuu, joten vahvista linkitys lukemalla agentin tiedot uudelleen.

Verkkosivun tuominen #

POST /kb-sources/url

Lisää yhden verkkosivun tietokantaasi.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

Vastaus — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

Kysy source_id-tilaa Tarkista lähde -toiminnolla, kunnes tila on ready tai failed.

Jos sama sivu on jo tietopohjassasi, mitään uutta ei aseteta jonoon ja saat sen sijaan 200-vastauksen – ja jos pyysit automaattista linkitystä, olemassa oleva lähde linkitetään sinulle joka tapauksessa:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

Puuttuva url tai osoite, joka ei ole kelvollinen http/https-osoite, palauttaa 400-vastauksen.

Tuo ladattu tiedosto #

POST /kb-sources/file

Lisää tiedoston, joka on jo tilisi tiedostotallennustilassa, tietolähteeksi. Tuetut tyypit: PDF, DOCX, TXT, MD, CSV ja XLSX.

Tämä päätepiste ei sisällä itse tiedostoa. Siinä ei ole multipart-lähetystä, base64-runkoa eikä URL-osoitteesta lataamista: lähetät tiedoston tallennussijainnin, jonka on oltava omassa latauskansiossasi (storage_path täytyy alkaa users/{your user id}/uploads/-merkkijonolla), muuten pyyntö hylätään 403-vastauksella. Hallintapaneeli sijoittaa tiedostot sinne, kun raahaat ne sisään. Jos et pysty sijoittamaan tiedostoa sinne, tuo verkkosivu käyttämällä Tuo verkkosivu -toimintoa.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

Vastaus — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Tarkista lähde #

GET /kb-sources/{sourceId}

Kysely, joka seuraa jokaista tuontia ja päivitystä. Toista sitä, kunnes tila on ready tai failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

Vastaus

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}

Poista lähde #

DELETE /kb-sources/{sourceId}

Poistaa yhden tietolähteen. Oletusarvoisesti sen tuottamat UKK:t säilytetään — lisää delete_faqs=true poistaaksesi myös ne.

Kyselyparametrit

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

Vastaus

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted on 0, ellet pyytänyt delete_faqs=true.

Tuo useita sivuja kerralla #

POST /kb-sources/bulk-import

Lisää jopa 100 verkkosivua yhdellä kutsulla. Tililläsi voi olla kerrallaan enintään 5 000 sivua odottamassa tuontia (tilisi tuontiraja), mukaan lukien jo jonossa olevat tai luettavana olevat sivut. Kutsu, joka ylittäisi tämän rajan, hylätään virheillä 400 ja error_code: kb_import_page_limit, eikä mitään kyseisestä kutsusta lisätä jonoon. Yli 5 000 sivun tuonnit vaativat hyväksynnän, joten ota yhteyttä tukeen rajan nostamiseksi. Tämä on tavanomainen jatkotoimenpide toiminnoille Löydä sivuja verkkosivustolta tai Etsi uusia sivuja verkkosivustolta. Tietokannassasi jo olevat sivut ohitetaan sen sijaan, että ne kopioitaisiin (ja ne pysyvät linkitettyinä agenttiin, jos niin pyysit).

Tuonti, jota tilisi ei voi maksaa, hylätään ennen kuin mitään lisätään jonoon, virheillä 402 ja error_code: kb_import_insufficient_credits (vastaus sisältää myös required_credits, available_credits ja waiting_pages). Jokainen sivu lasketaan vähintään yhdeksi lohkoksi tätä tarkistusta varten, ja myös jo tuontia odottavat sivut lasketaan mukaan, koska niistä veloitetaan vasta, kun ne käsitellään. Tilejä, joilla on automaattinen täydennys käytössä, ei hylätä saldon perusteella. Tilejä, jotka käyttävät omaa tekoälyavaintaan, ei myöskään hylätä, elleivät ne toimi Max-tasolla, josta veloitetaan krediitteinä. Alitilin kohdalla available_credits on null.

Yli 100 sivun tuominen tarkoittaa useita kutsuja. Lähetä koko valinnan koko arvona plannedTotal ensimmäisessä kutsussa. Sivuraja ja krediittitarkistus kattavat tällöin koko valinnan kyseisessä kutsussa, joten tuonti, jota ei voida viedä loppuun, hylätään ennen kuin yhtäkään sivua jonotetaan, sen sijaan että se pysähtyisi kesken kaiken. Kun ensimmäinen kutsu hyväksytään, sen vastaus sisältää tunnisteen import_session: lähetä se takaisin arvona importSession jokaisessa saman valinnan myöhemmässä kutsussa. Nämä kutsut ohittavat tällöin ennakkokrediittitarkistuksen hyväksyttyyn sivumäärään asti yhden tunnin ajan. Sivuraja on edelleen voimassa, ja jokaisesta sivusta veloitetaan edelleen, kun se käsitellään.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

Vastaus — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

Kysy jokaisen tunnuksen tilaa kohdassa queued_source_ids käyttämällä Tarkista lähde-toimintoa. Tyhjän urls-taulukon, ei-merkkijonomuotoisen merkinnän tai yli 100 merkinnän lähettäminen palauttaa 400.

Poista useita lähteitä kerralla #

POST /kb-sources/bulk-delete

Poistaa jopa 2 000 tietolähdettä yhdellä kutsulla. Poisto suoritetaan taustalla, ja saat sähköpostin, kun se on valmis.

Massapoisto poistaa aina myös UKK-osiot. Toisin kuin Poista lähde, joka säilyttää ne, ellet toisin pyydä, tämä päätepiste poistaa jokaisen lähteen yhdessä sen tuottamien UKK-osioiden kanssa. Niiden säilyttämiseen ei ole vaihtoehtoa.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

Vastaus — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

Sivujen etsiminen verkkosivustolta #

POST /kb-sources/discover-pages

Tutkii verkkosivustoa yhdestä aloitusosoitteesta alkaen ja listaa samasta verkkotunnuksesta löytyneet sivut sekä arvion siitä, kannattaako ne tuoda. Mitään ei tuoda eikä mitään valita puolestasi — tämä on “mitä sivustolla on” -vaihe, joka suoritetaan ennen kuin päätät, mitä lähetät Tuo useita sivuja kerralla -toimintoon.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

Vastaus

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}

Tutkiminen on parhaan yrityksen periaatteella toimivaa. Jos sivustoa ei voida lukea, vastaus on silti 200, sisältäen success: false, tyhjän pages-listan ja error-viestin. Tarkista success ennen kuin luet pages.

Puuttuva url palauttaa 400.

Tuonnin kustannusarvio #

POST /kb-sources/estimate-cost

Laskee, kuinka monta krediittiä ehdotettu tuonti kuluttaisi, ennen kuin vahvistat sen. Sivut haetaan ja asiakirjat luetaan niiden koon mittaamiseksi, mutta mitään ei tuoda, eikä itse arvio kuluta krediittejä.

Pyynnön kentät

Lähetä urls, files tai molemmat.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

Vastaus

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7,
  "affordable": true,
  "required_credits": 7,
  "available_credits": 120,
  "checked_chunks": 7,
  "waiting_pages": 0,
  "max_affordable_chunks": 120
}

Jokainen rivi toistaa URL-osoitteen tai tallennuspolun kohteessa ref, jotta voit yhdistää sen syötteeseesi. Sivu tai tiedosto, jota ei voitu lukea, saa silti rivin, joka lasketaan yhdeksi lohkoksi, ja siinä on error.

affordable kertoo, voiko tilisi maksaa tämän arvion, laskien mukaan jo tuontia odottavat sivut (waiting_pages). max_affordable_chunks on suurin määrä lisälohkoja, jotka voidaan maksaa, joten voit seurata juoksevaa summaa, kun arvioit suurta valintaa useassa kutsussa. Se on null, kun saldosi ei rajoita sinua (automaattinen täydennys käytössä tai oma tekoälyavain alle Max-tason), ja aina null alitilille, joka saa vain affordable (lähetä prior_chunks, jotta se kattaa koko valinnan) ja null available_credits.

Tuonnin pysäyttäminen #

POST /kb-sources/cancel-import

Pysäyttää tuontijonossa odottavat sivut – “pysäytä tuonti” -painike indeksoinnille, joka osoittautui odotettua suuremmaksi. Odottavan sivun peruuttaminen ei maksa mitään, koska sitä ei ole vielä luettu.

Jo käsiteltäviä sivuja ei pysäytetä: niiden työ on käynnissä ja niistä veloitetaan joka tapauksessa, joten ne valmistuvat. Vastaus kertoo, kuinka monta niitä oli.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

Vastaus

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

Keskeytetyn tuonnin jatkaminen #

POST /kb-sources/resume-import

Käynnistää uudelleen tuonnin, joka keskeytettiin, koska oma AI-avaimesi lakkasi toimimasta.

Tämän kutsuminen on suostumuksesi tuonnin viimeistelyyn sillä avaimella, joka on tällä hetkellä aktiivinen – mikä voi tarkoittaa alustan krediittien käyttöä, jos oma avaimesi on edelleen alhaalla.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Vastaus

{
  "success": true,
  "resumed": 58
}

Uusien sivujen etsiminen verkkosivustolta #

POST /kb-sources/refresh-domain

Tutkii verkkosivuston, jolta olet jo tuonut tietoja, ja raportoi vain ne sivut, jotka eivät ole vielä tietokannassasi. Jokaisella on sama suositus kuin sivun löytämisessä. Mitään ei tuoda eikä mitään muuteta.

Nämä kaksi jatkotoimenpidettä ovat tarkoituksella erillisiä kutsuja, joten tästä poistuminen ei maksa mitään:

• tuo uudet haluamasi sivut käyttämällä Tuo useita sivuja kerralla;
• lue uudelleen jo olemassa olevat sivut käyttämällä Päivitä verkkosivuston jokainen sivu.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Vastaus

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}

Päivitä verkkosivuston jokainen sivu #

POST /kb-sources/trigger-domain-refresh

Lukee uudelleen jokaisen sivun, jonka olet jo tuonut verkkosivustolta, jotta sen UKK-osiot vastaavat sivuston nykyistä sisältöä: muuttuneet osiot päivitetään, uudet osiot lisätään ja poistetut osiot poistetaan.

Tämä asettaa työn jonoon ja palauttaa vastauksen välittömästi. Seuraa sitä Seuraa verkkosivuston päivitystä -toiminnolla ja pysäytä se Pysäytä verkkosivuston päivitys -toiminnolla.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Vastaus

{
  "success": true,
  "queued": 249
}

Seuraa verkkosivuston päivitystä #

GET /kb-sources/domain-refresh-status

Kuinka pitkällä verkkosivuston päivitys on, jotta voit näyttää edistymisen muodossa “221 / 249”.

Kyselyparametrit

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

Vastaus

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

job on null, kun kyseiselle verkkosivustolle ei ole käynnissä päivitystä. Tähän mennessä valmistuneet sivut ovat total miinus pending. Työ status on jokin seuraavista: refreshing (käsittelee vielä sivuja), deduplicating (lopussa tehtävä puhdistusvaihe) tai lopullinen completed, failed ja cancelled. Säilytä domainBatchId – se on se, jonka välität peruutus-päätepisteelle.

Puuttuva tai tyhjä baseUrl palauttaa 400.

Pysäytä verkkosivuston päivitys #

POST /kb-sources/refresh-domain/cancel

Pysäyttää verkkosivuston päivityksen, joka käsittelee vielä sivujaan. Jo valmistuneet sivut säilyttävät päivitetyn sisältönsä; aloittamattomat sivut hylätään, ja uudelleenluettavana olleet sivut palautuvat aiempaan tilaansa.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

Vastaus

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}

Kahdesti peruuttaminen on vaaratonta – toinen kutsu raportoi saman lopputilan. Kun päivitys on siirtynyt siivousvaiheeseen, sitä ei voi enää pysäyttää, ja vastaus palauttaa success: false ja reason: "already_finalizing". Puuttuva jobId palauttaa 400, ja tiliisi kuulumaton työ palauttaa 404.

Päivitä yksittäinen lähde #

POST /kb-sources/{sourceId}/refresh

Lukee uudelleen yhden jo tuomasi verkkosivun ja päivittää sen UKK-osiot vastaamaan sivun nykyistä sisältöä: muuttuneet osiot päivitetään, uudet lisätään ja poistetut poistetaan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

Vastaus — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Kysy lähteen tilaa, kunnes se ei ole enää queued tai processing. Tiliisi kuulumaton lähdetunnus palauttaa 404.

Valitse osuvimmat sivut #

POST /kb-sources/select-relevant-pages

Pyytää tekoälyä valitsemaan ehdokaslistalta viisi sivua, jotka kuvaavat yritystä parhaiten – käytetään kampanjan pelikirjan luomiseen verkkosivustosta. Tämä kuluttaa krediittejä.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

Vastaus

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

Tämä on apuohjelma, ei resurssi: virhetilanteessa se vastaa silti 200, success: false, tyhjällä pages-listalla ja error-viestillä.

Tietoryhmät #

Tietoryhmä on nimetty UKK-kokoelma – esimerkiksi “Toimitus ja palautukset” tai “Perehdytys” – jonka voit liittää agenttiin tai kampanjaan yhdellä kutsulla. Ryhmä sisältää viittauksia, ei kopioita: itse UKK-kysymykset pysyvät yhdessä kirjastossasi, joten yhden muokkaaminen UKK-rajapinnan kautta päivittää sen kaikkialla, missä sitä käytetään.

Ryhmän liittäminen lisää aina vain puuttuvat osat, joten saman ryhmän liittäminen kahdesti on vaaratonta ja added_count palauttaa 0 toisella kerralla.

Luo tietoryhmä #

POST /kb-groups

Luo ryhmän. Se on aluksi tyhjä – lisää siihen UKK-kysymyksiä kohdasta Lisää UKK ryhmään.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

Vastaus — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

Nimeä tietoryhmä uudelleen #

PUT /kb-groups/{groupId}

Muuttaa ryhmän nimen. Sen sisältämät UKK-kysymykset säilyvät ennallaan.

Pyynnön kentät

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

Vastaus

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

Poista tietoryhmä #

DELETE /kb-groups/{groupId}

Poistaa ryhmän. Vain kokoelma poistetaan – siinä olevat UKK-kysymykset säilyvät kirjastossasi, ja kaikki kohteet, joihin ryhmä oli jo liitetty, säilyttävät kyseiset UKK-kysymykset.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

Vastaus

{
  "success": true
}

Lisää UKK ryhmään #

POST /kb-groups/{groupId}/faqs

Lisää olemassa olevan UKK:n ryhmään. Tämä muuttaa vain ryhmittelyä – se ei itsessään liitä UKK:ta mihinkään agenttiin; käytä ryhmää siihen tarkoitukseen.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

Vastaus

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Poista UKK ryhmästä #

DELETE /kb-groups/{groupId}/faqs/{faqId}

Poistaa UKK:n ryhmästä. Itse UKK:ta ei poisteta, ja agentit, joille ryhmä on jo määritetty, säilyttävät sen.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

Vastaus

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Määritä ryhmä agentille #

POST /kb-groups/{groupId}/apply-to-agent

Lisää jokaisen ryhmän UKK:n tekoälyagentin tietopohjaan yhdellä kutsulla – tämä on nopein tapa antaa uudelle agentille valmiiksi kuratoitu tietopohja.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

Vastaus

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count kertoo, kuinka monta UKK:ta todellisuudessa lisättiin – 0, jos ryhmä on tyhjä tai jo määritetty.

Määritä ryhmä kampanjalle #

POST /kb-groups/{groupId}/apply-to-campaign

Edellisen kutsun versio perinteisille kampanjoille. Agenttipohjaisella tilillä käytä sen sijaan Määritä ryhmä agentille-toimintoa.

Pyynnön kentät

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

Vastaus

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

Knowledge Base API -virheet #

Nämä päätepisteet palauttavat vakiomuotoisen virhekuoren:

{
  "success": false,
  "error": "Knowledge base source not found."
}

Pehmeät virheet eivät ole varsinaisia virheitä. Discovery (discover-pages, refresh-domain) ja sivunvalinta-apuohjelma vastaavat 200-koodilla success: false ja error-viestillä, kun verkkosivustoa ei voida lukea, sen sijaan että pyyntö epäonnistuisi. Tarkista aina success ennen tietojen lukemista.

Jaetut koodit, joita jokainen päätepiste voi palauttaa — 401, 403 (tilauksesi ei sisällä API-käyttöoikeutta), 429 (nopeusrajoitus) ja 500 — on lueteltu uudelleenyritysohjeiden kera kohdassa Virheet ja sivutus.

Aiheeseen liittyvää #

• FAQs API – lue, muokkaa ja linkitä lähteidesi tuottamia FAQ-osioita.
• FAQ-osioiden hallinta – sama tietokanta hallintapaneelissa.
• AI-agentit – agentit, joihin liität lähteitä ja ryhmiä.
• API-käyttöoikeus – luo API-avaimesi.
• Todennus – kaikki tavat välittää avaimesi.