# API:n käytön aloittaminen

<span data-t="appName">Your AI Connector</span> REST API mahdollistaa omien integraatioiden rakentamisen tilisi päälle. Voit luoda ja etsiä yhteystietoja, hallinnoida kampanjoita, UKK-osioita, tehtäviä ja tapaamisia, lähettää viestejä, rekisteröidä webhookeja, lukea analytiikkaa ja yhdistää viestintäkanavia — kaikki mitä hallintapaneelissa voi tehdä, onnistuu myös koodilla.

Tämä on API-dokumentaation keskeinen sivu. Jos yhdistät <span data-t="appName">Your AI Connector</span>-palvelun työkaluun, jossa on jo valmis integraatio, et ehkä tarvitse API:a lainkaan. API on tarkoitettu mukautettuja integraatioita ja laajamittaista automaatiota varten.

::: note
**Huomautus:** Nämä sivut on kirjoitettu kehittäjille. Jos et ole kehittäjä, jaa tämä osio teknisen tiimisi kanssa.
:::


---

## Perus-URL

Jokainen pyyntö lähetetään samaan perusverkko-osoitteeseen, ja kaikki näiden dokumenttien polut ovat suhteellisia siihen nähden:

```
https://api.youraiconnector.com/v1
```

Joten kampanjoiden päätepiste on `https://api.youraiconnector.com/v1/campaigns`, yhteystietojen päätepiste on `https://api.youraiconnector.com/v1/contacts`, ja niin edelleen.

Kaikissa pyynnöissä on käytettävä suojattua yhteyttä (HTTPS). Tavalliset HTTP-pyynnöt hylätään.

---

## API-avaimen hankkiminen

API-käyttöoikeus on **maksullinen ominaisuus**. Jos tilauksesi ei sisällä sitä, jokainen pyyntö palauttaa `403`-vastauksen, jonka runko on seuraava:

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

Kun API-käyttöoikeus on otettu käyttöön tilauksessasi, luo avain hallintapaneelista. Täydelliset vaiheittaiset ohjeet löytyvät kohdasta [API Access](../integrations/api-access.md) — lyhyesti: siirry kohtaan **Settings → Integrations → API Key** luodaksesi tai luodaksesi avaimen uudelleen. API Key on oma osionsa Integrations-kohdassa, erillään Webhookeista, ja se näkyy vasta, kun API-käyttöoikeus on aktivoitu tilauksessasi. Käsittele avainta kuin salasanaa: se antaa täyden pääsyn tilillesi.

---

## Todennus

Voit lähettää API-avaimesi neljällä eri tavalla. Kaikki ne toimivat jokaisessa päätepisteessä, joka hyväksyy API-avaintunnistautumisen.

| Menetelmä | Miten | Paras käyttökohde |
|---|---|---|
| Kyselyparametri | `?apiKey=YOUR_API_KEY` | Pikatestit, selaimen URL-osoitteet, vanhat järjestelmät |
| Otsikko (Header) | `X-API-Key: YOUR_API_KEY` | Tuotanto-integraatiot |
| Bearer-otsikko | `Authorization: Bearer YOUR_API_KEY` | Tuotanto-integraatiot |
| Firebase ID -tunniste | `Authorization: Bearer <ID token>` | Vain ensimmäisen osapuolen sovellusistunnot |

Tuotantokäytössä suosi jotakin otsikkomuotoa, jotta avaimesi ei koskaan päädy palvelimen lokiin tai selaimen historiaan. Kyselyparametrimuoto toimii aina ja on yksinkertaisin kertaluonteisiin testeihin.

Katso [Tunnistautuminen](authentication.md) nähdäksesi täydellisen erittelyn jokaisesta menetelmästä, esimerkkeineen ja ohjeineen siitä, milloin mitäkin kannattaa käyttää.

---

## Ensimmäinen pyyntösi

Tässä on täydellinen, toimiva kutsu, joka listaa tilisi kampanjat. Se käyttää API-avaintasi ja palauttaa uusimmat kampanjat ensin.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])
```

Onnistunut vastaus näyttää tältä:

```json
{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}
```

---

## Onnistumis- ja virhevastaukset

Jokainen JSON-vastaus sisältää `success`-lipun, joten voit tehdä haarautumisen sen perusteella ilman tilakoodien jäsentämistä.

Onnistunut vastaus on `success: true` sekä kyseisen päätepisteen tiedot (kentän nimi vaihtelee — `campaigns`, `contacts`, `data` jne.):

```json
{
  "success": true,
  "campaigns": []
}
```

Epäonnistunut vastaus on `success: false`, joka sisältää ihmisluettavan `error`-viestin ja numeerisen `error_code`-arvon, joka vastaa HTTP-tilaa:

```json
{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}
```

Tarkista aina `success` (tai HTTP-tila) ennen tietojen lukemista. Katso [Virheet ja sivutus](errors-and-pagination.md) nähdäksesi täydellisen tilakooditaulukon ja ohjeet suurten tulosjoukkojen selaamiseen.

---

## Nopeusrajoitukset

Todennetut pyynnöt on rajoitettu **300 pyyntöön minuutissa** per API-avain. Lisäksi käytössä on laajempi **1 200 pyynnön yläraja minuutissa per tili**, joka laskee jokaisen kyseiselle tilille tehdyn todennetun pyynnön.


Jos ylität kumman tahansa rajan, saat `429`-vastauksen:

```json
{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}
```

Pidä tauko ja yritä uudelleen lyhyen odotuksen jälkeen. Voit myös tarkistaa nykyisen käyttösi milloin tahansa `GET https://api.youraiconnector.com/v1/api-keys/usage`-kutsulla, joka palauttaa tiedon siitä, kuinka monta pyyntöä olet käyttänyt nykyisessä ikkunassa ja milloin se nollautuu — tämä on hyödyllistä asiakaspuolen rajoitusten rakentamisessa. Katso [API-avaimet](api-keys.md).

---

## Resurssioppaat

Alla olevilla resurssiryhmillä on kullakin oma oppaansa, joka sisältää tarkat polut, pyyntökentät ja vastausmuodot.

| Resurssi | Mitä se kattaa |
|---|---|
| [AI-agentit](agents.md) | Luo ja määritä AI-agentteja: asetukset, aktiiviset tunnit, tietämys, tunnistesäännöt, työkalut, media ja luonnokset |
| [Sisääntulopisteet](entry-points.md) | Päätä, mikä AI-agentti vastaa uuteen keskusteluun: kanavien oletusasetukset, yksi agentti per WhatsApp-numero, avainsana-, kommentti- ja seuraajasäännöt |
| [Lähetykset](broadcasts.md) | Luo, hinnoittele, käynnistä, keskeytä ja kopioi kertaluonteisia lähetyksiä yhteystietoluetteloon |
| [Kampanjat](campaigns.md) | Luo, päivitä, kopioi, ota käyttöön, arkistoi ja tarkastele kampanjoita sekä niiden bottikonfiguraatiota |
| [Yhteystiedot](contacts.md) | Luo, etsi, listaa, päivitä, tuo, merkitse ja poista yhteystietoja |
| [UKK](faqs.md) | Hallitse kysymys-vastaus-merkintöjä, joita AI-avustajasi käyttää, ja linkitä ne kampanjoihin |
| [Tietopankki](knowledge-base.md) | Tuo verkkosivustoja ja asiakirjoja AI-agenttisi tietämykseen ja ryhmittele UKK-osiot |
| [Tehtävät](tasks.md) | Luo ja hallitse CRM-tehtäviä, taulun vaiheita ja tehtävätyyppejä |
| [Viestit](messages.md) | Lähetä lähteviä viestejä ja lue keskusteluhistoriaa |
| [Ajanvaraukset](appointments.md) | Varaa, siirrä, peruuta ja poista ajanvarauksia |
| [Kanavat](channels.md) | Yhdistä ja katkaise viestintäkanavia, osta numeroita ja määritä, mikä AI-agentti vastaa uusiin keskusteluihin kullakin kanavalla |
| [Mallipohjat](templates.md) | Luo, lähetä ja tarkista WhatsApp-viestipohjien hyväksymistila |
| [Analytiikka](analytics.md) | Lue päivittäisiä viestitapahtumien tilastoja, krediittien käyttöä ja AI-kustannusten yhteenvetoja |
| [Webhookit](webhooks.md) | Rekisteröi päätepisteitä reaaliaikaisten tapahtumailmoitusten vastaanottamiseksi |
| [Tiimi](team.md) | Hallitse tiimin jäseniä, kutsuja, rooleja, käyttöoikeuksia ja osastoja |
| [API-avaimet](api-keys.md) | Tarkastele, kierrätä ja peruuta API-avaimesi, tarkista nopeusrajoitusten käyttö ja luo lisäavaimia rajoitetulla pääsyllä |

### Agentit, sisääntulopisteet ja lähetykset

AI-agentit, sisääntulopisteet ja lähetykset ovat kaikki julkaistussa OpenAPI-määrityksessä, joten voit selata niiden tarkkoja kenttiä ja suorittaa niitä vastaan live-pyyntöjä [API-selaimessa](reference.md). Jokaisella on oma oppaansa: [AI-agentit](agents.md), [Sisääntulopisteet](entry-points.md) ja [Lähetykset](broadcasts.md).


---

## Näiden ohjeiden lukeminen Markdown-muodossa

Jokaisella tämän dokumentaation sivulla on Markdown-vastine: lisää sivun osoitteen loppuun `/index.md`. Tämä sivu on siis saatavilla myös osoitteesta `https://docs.youraiconnector.com/api/getting-started/index.md`, ja se palautuu selkeänä tekstinä verkkosivun sijaan – tämä on kätevää, kun haluat liittää sivun tekoälyavustajaan tai hakea sen skriptiin.

Voit selata koko aineistoa aloittamalla osoitteesta `https://docs.youraiconnector.com/sitemap.xml`, joka listaa kaikki julkaisemamme sivut. Huomaa, että dokumentaatio on tarkoituksella jätetty hakukoneiden ulkopuolelle, joten näiden osoitteiden suora hakeminen on oikea tapa käyttää niitä koodista käsin.

Dokumentaatiolle ei ole vielä avainten suojaamaa päätepistettä eikä massalatausmahdollisuutta – Markdown-vastineet ja sivukartta muodostavat koko rajapinnan, eikä kumpikaan niistä vaadi API-avainta.

---

## Seuraavat vaiheet

- [Todennus](authentication.md) — valitse integraatiollesi oikea todennusmenetelmä.
- [Virheet ja sivutus](errors-and-pagination.md) — käsittele virheet ja selaa tuloksia sivuittain.
- [API-pääsy](../integrations/api-access.md) — luo avaimesi ja katso käytännön esimerkkejä.