# AI Agents-API

En **AI-agent** är hjärnan bakom din bot: dess instruktioner, personlighet, språk, kunskap och verktyg. Du bygger en agent en gång och dirigerar sedan trafik till den. Den här guiden täcker allt du kan göra med en agent via API:et — skapa den, konfigurera den, ge den kunskap och verktyg, granska dess utkast och dirigera konversationer till den.

- **Bas-URL** — `https://api.youraiconnector.com/v1`
- **Autentisering** — din API-nyckel (se [Autentisering](authentication.md))
- **Fel och sidnumrering** — se [Fel och sidnumrering](errors-and-pagination.md)

Alla exempel nedan visar frågeformuläret `?apiKey=` i cURL och headern `X-API-Key` i JavaScript och Python — båda fungerar på alla slutpunkter.

Om du är ny inför konceptet agenter, läs [AI-agenter](../ai-agents/ai-agents.md) först.


---

## Hur en agent är uppbyggd

Fyra delar hanteras separat, och det är bra att veta vilken som är vilken innan du börjar:

| Del | Vad det är | Var du ställer in det |
|---|---|---|
| **Konfiguration** | Instruktioner, regler, mål, personlighet, språk, AI-nivå, bokning och uppföljningsbeteende | `PUT /agents/{agentId}` eller den mer specifika `PUT /agents/{agentId}/bot-config` |
| **Kunskap** | FAQ och kunskapskällor (sidor och dokument som plattformen har läst åt dig) | [FAQs API](faqs.md) och `POST /agents/{agentId}/kb-sources` |
| **Verktyg** | Anpassade funktioner och MCP-servrar som agenten kan anropa mitt i en konversation | `POST /agents/{agentId}/custom-functions` och `POST /agents/{agentId}/mcp-servers` |
| **Dirigering** | Vilka kanaler och konversationer som faktiskt når denna agent | Ingångspunkter — `PUT /entry-points/channel-defaults` och `POST /agents/{agentId}/entry-points` |

> **En ny agent svarar ingen förrän du dirigerar trafik till den.** Att skapa en agent innebär inte att den läggs till i en kanal. Det är det steg som de flesta integrationer missar — se [Dirigera konversationer till en agent](#routing-conversations-to-an-agent) i slutet av den här sidan.

---

## Agent-objektet

Ett fullständigt agentdokument är stort — flera hundra kilobyte, främst dess FAQ-lista, dess kunskapskällor och allt sidinnehåll som lästs från din webbplats. På grund av detta returnerar listningen en kort **sammanfattningsrad** per agent när du efterfrågar den:

```json
{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| Fält | Typ | Beskrivning |
|---|---|---|
| `id` | string | Agentens unika identifierare. |
| `name` | string \| null | Agentens namn, så som det visas i kontrollpanelen. |
| `active` | boolean \| null | Om agenten för närvarande tillåts svara. |
| `language` | string \| null | Språket agenten svarar på. |
| `goal` | string \| null | Vad agenten arbetar mot, förkortat till de första 200 tecknen (en avslutande ellips betyder att texten förkortats). |
| `tags` | array \| null | Agentens taggningsregler. |
| `anthropic_model` | string \| null | AI-kvalitetsnivå: `standard`, `economy`, `max` eller `mini`. |
| `ai_speed` | string \| null | Hur mycket resonemang agenten tillämpar innan den svarar: `fast`, `fast_thinker`, `balanced` eller `thorough`. |
| `enable_bookings` | boolean \| null | Om agenten får boka möten. |
| `enable_follow_ups` | boolean \| null | Om agenten skickar uppföljningsmeddelanden. |
| `faq_refs_count` | integer | Hur många FAQ-frågor som finns i agentens kunskapsbas. |
| `kb_source_refs_count` | integer | Hur många kunskapskällor som är länkade till den. |
| `created_at` | integer \| null | Skapandetid, epok-millisekunder. |
| `last_modified_at` | integer \| null | Senaste ändring, epok-millisekunder. |

Det fullständiga dokumentet lägger till allt annat: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, de länkade FAQ- och kunskapskälllistorna, de genererade textblocken och eventuell körstatus (`tag_generation`, `optimize_run`).

> Vissa svar innehåller även `substrate_campaign_id`. Det är ett internt register som sparas på äldre konton; du behöver aldrig agera på det, och på nyare konton är det `null` eller saknas helt.

---

## Lista agenter

`GET /agents` — varje agent på kontot, de nyaste först.

Denna slutpunkt är **inte paginerad**. Som standard returneras varje Agent med sin fullständiga konfiguration, vilket är tungt: en enskild Agent kan nå 580 KB och ett konto med 64 agenter över 3 MB. Skicka `view=summary` för en kort rad per Agent istället, och läs sedan den du vill ha med [Hämta en Agent](#get-an-agent).

**Frågeparametrar**

| Parameter | Beskrivning |
|---|---|
| `view` | Sätt till `summary` för korta rader. Alla andra värden returnerar `400`. Utelämna för fullständiga dokument. |
| `fields` | Gäller endast tillsammans med `view=summary`. Kommaseparerade sammanfattningsnycklar att behålla, till exempel `id,name,active`. `id` inkluderas alltid; okända namn ignoreras. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

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

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]
```

**Svar** (`200`)

```json
{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}
```

---

## Skapa en Agent

`POST /agents` — endast `name` behövs egentligen; skicka med vilken konfiguration du redan känner till. En ny Agent är aktiv som standard.

**Begäransfält** (alla valfria förutom `name`)

| Fält | Typ | Beskrivning |
|---|---|---|
| `name` | string | Agentens namn. |
| `active` | boolean | Om den får svara direkt. Standard är `true`. |
| `language` | string | Språket som Agenten svarar på. |
| `instructions` | string | Primära instruktioner som styr hur den pratar med kontakter. |
| `rules` | string | Hårda regler som den alltid måste följa. |
| `goal` | string | Resultatet den bör arbeta mot. |
| `personality` | string | Tonläge och personlighet. |
| `availability` | object | Aktiva timmar per veckodag — se [Ställ in aktiva timmar](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` eller `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` eller `mini`. |
| `scrape_urls` | string[] | Sidor att läsa och bygga Agentens instruktioner från. |

**Bygga en Agent från din webbplats.** Inkludera `scrape_urls` så läser plattformen dessa sidor och skriver instruktionerna åt dig. Svaret talar om för dig om genereringen har startat, så att du vet om du ska fråga Agenten om framsteg.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);
```

**Python**

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])
```

**Svar** (`201`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}
```

`agent_generation_queued` är `true` när plattformen har börjat skriva instruktionerna från sidorna du tillhandahöll.

Ett `400` innebär att brödtexten inte var ett JSON-objekt, ett fält avvisades eller att Agenten överskrider den konfigurationsstorlek som din plan tillåter. Ett `403` innebär att kontot inte har tillåtelse att använda en av inställningarna du skickade — till exempel en AI-nivå som kontots leverantör inte har beviljat.

---

## Hämta en Agent

`GET /agents/{agentId}`

Skicka `fields` med en kommaseparerad lista för att bara få tillbaka det du behöver, till exempel `fields=name,active,goal`. `id` inkluderas alltid, och namn som inte finns på Agenten ignoreras istället för att avvisas. Utelämna den för att få hela dokumentet.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]
```

En Agent som inte finns på ditt konto returnerar `404`.

---

## Uppdatera en Agent

`PUT /agents/{agentId}` — skicka endast de fält du vill ändra; allt annat lämnas orört.

Kapslade inställningar kan adresseras blad för blad med en punktmarkerad nyckel, så `"availability.monday"` ändrar bara måndag och lämnar resten av veckan orörd.

**Anteckningar**

- För att ändra vilken bokningsbar händelsetyp agenten bokar in i, skicka `event_id` (händelsens id, eller `null` för att rensa det). Skicka `event_ids` med en array för att länka flera samtidigt — den första blir den primära och `[]` avlänkar allt. `event_id` och `event_ids` är ömsesidigt uteslutande, och fältet `event` i sig kan inte skrivas direkt.
- `enable_bookings` måste vara ett faktiskt booleskt värde, och `booking_provider` måste vara ett av `default`, `zenchef`, `formitable`.
- Ägarskaps- och identitetsfält ignoreras, liksom internt körningstillstånd (genererings- och optimeringsförlopp).
- **Routing ställs inte in här.** Använd `PUT /entry-points/channel-defaults` för att göra agenten till svarare för en kanal, `POST /agents/{agentId}/entry-points` för nyckelords- och kommentarsregler, och `PATCH /agents/{agentId}/active` för att pausa eller återuppta den.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'
```

**JavaScript**

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});
```

**Python**

```python
requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)
```

**Svar** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

En tom brödtext returnerar `400` med `"No fields to update"`.

---

## Uppdatera botinställningar

`PUT /agents/{agentId}/bot-config` — det begränsade sättet att bara ändra konversationsinställningarna.

En agent har ingen separat botsektion: dess inställningar ligger direkt på agenten, så fältnamnen här är desamma som du skulle skicka till `PUT /agents/{agentId}`. Denna slutpunkt finns som det säkra, fokuserade sättet att ändra ett fåtal av dem. Minst ett fält krävs.

| Fält | Beskrivning |
|---|---|
| `instructions` | Primära instruktioner som styr hur agenten pratar med kontakter. |
| `rules` | Hårda regler som den alltid måste följa. |
| `goal` | Resultatet den bör arbeta mot i varje konversation. |
| `personality` | Beskrivning av tonläge och personlighet. |
| `language` | Språket agenten svarar på. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` eller `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` eller `mini`. |
| `max_messages` | Maximalt antal agentmeddelanden per konversation. |
| `alert_human_when` | När agenten bör varna en mänsklig teammedlem. |
| `ai_transparency` | Huruvida agenten avslöjar att den är en AI. |

> **Fältnamn måste vara enkla namn här** — bokstäver, siffror, understreck och bindestreck. Punktmarkerade sökvägar accepteras inte på denna slutpunkt (till skillnad från `PUT /agents/{agentId}`), så `bot.goal` avvisas med ett `400`.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'
```

Lång text räknas mot den konfigurationsstorlek din plan tillåter, så en mycket stor instruktionsuppsättning kan nekas med ett `400`.

---

## Ställ in aktiva timmar

`PUT /agents/{agentId}/active-hours` — timmarna under vilka agenten svarar automatiskt. Utanför dessa fönster förblir den tyst.

Skicka ett `availability`-objekt med nycklar för veckodag (`monday` till `sunday`). Varje dag tar ett enskilt tidsfönster eller en lista med fönster, i 24-timmars `HH:MM`-format. Dagar du utelämnar behåller vad de hade, och varje nyckel som inte är en veckodag avvisas — så ett skrivfel kan inte tyst göra ingenting.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**Svar** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

En felaktig veckodagsnyckel returnerar `400`: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Pausa eller återuppta en agent

`PATCH /agents/{agentId}/active` – aktiverar eller inaktiverar agenten. En pausad agent behåller all sin konfiguration men slutar svara omedelbart; återupptagning träder i kraft direkt.

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});
```

**Svar** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }
```

`active` måste vara ett faktiskt booleskt värde – allt annat returnerar `400` med `"active (boolean) is required"`.

---

## Duplicera en agent

`POST /agents/{agentId}/duplicate` – skapar en kopia med dess konfiguration bevarad. Kopian skickar ingenting förrän du pekar en kanal eller en ingångspunkt mot den.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"
```

**Svar** (`201`)

```json
{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }
```

En dubblett räknas mot din plans agentkvot precis som när du skapar en från grunden, så den nekas med `403` när kontot har nått sin gräns.

---

## Ta bort en agent

`DELETE /agents/{agentId}`

Borttagningen nekas så länge agenten fortfarande är kopplad till något som skulle sluta fungera utan den – en sändning, en ingångspunkt eller (på äldre konton) en kampanj. Svaret listar vad som håller kvar den så att du kan koppla bort dessa först och försöka igen.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"
```

**Svar** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

**Blockerad** (`409`)

```json
{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}
```

---

## Utkast: granska ändringar innan de publiceras

Redigeringar som görs i editorn, och alla omskrivningar som produceras av [Optimera med AI](#optimize-an-agent-with-ai), sparas som ett **opublicerat utkast** tills du publicerar dem. Den aktiva agenten fortsätter att svara med sin nuvarande konfiguration fram till dess.

### Publicera utkastet

`POST /agents/{agentId}/publish-draft` – flyttar utkastet till den aktiva konfigurationen och rensar utkastet i samma steg.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"
```

**Svar** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }
```

`published_keys` listar inställningarna som flyttades från utkastet till den aktiva agenten, så att du kan visa vad som ändrades.

> **Kontrollera att ett utkast finns innan du anropar detta.** Att publicera en agent som inte har något utkast är inte ett anrop som stöds och returnerar för närvarande en `500` med ett generiskt meddelande, inte ett specifikt. För att istället kasta bort ett utkast, använd discard nedan.

### Förkasta utkastet

`POST /agents/{agentId}/discard-draft` — kastar bort utkastet och lämnar den aktiva konfigurationen precis som den är. Det är säkert att anropa när det inte finns något utkast; ingenting händer.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"
```

---

## Optimera en agent med AI

`POST /agents/{agentId}/optimize` — skriver om agentens konfiguration baserat på din feedback ("den fortsätter erbjuda rabatter", "svaren är för långa") och sparar omskrivningen **som ett utkast** istället för att göra den aktiv.

Skicka antingen `user_feedback` (en enkel instruktion) eller, när du reagerar på ett specifikt dåligt svar, `thumbs_down_feedback` tillsammans med det felaktiga `thumbs_down_message`. Minst en av de två måste innehålla text.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'
```

**Svar** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Arbetet körs i bakgrunden och anropet returneras omedelbart. Läs agenten med `GET /agents/{agentId}` och bevaka `optimize_run.status`; när den är tillbaka till `Draft` väntar omskrivningen som agentens utkast. Granska det, och publicera eller förkasta det sedan.

Endast en körning åt gången per agent — ett andra anrop medan en körning pågår returnerar `409`. Detta förbrukar AI-krediter.

---

## Taggregler

En taggregel består av en tagg plus en beskrivning av när den ska tillämpas. Under en konversation läser agenten beskrivningen och taggar kontakten när det passar, vilket är hur taggdrivna automatiseringar utlöses.

**Regelobjektet**

| Fält | Krävs | Beskrivning |
|---|---|---|
| `name` | Ja | Taggen som ska tillämpas, till exempel `hot-lead`. |
| `description` | Nej | När agenten ska tillämpa den, skrivet som en instruktion den följer. |
| `webhook` | Nej | URL som anropas när agenten tillämpar denna tagg. |
| `ai_can_remove` | Nej | Huruvida agenten även får ta bort taggen igen. Standardvärde är `false`. |
| `tag_id` | Nej | ID för en befintlig tagg på ditt konto för att länka regeln till. Utan detta länkas regeln till taggen med samma namn, och skapar den om den inte finns — så att varje regel kan adresseras via tagg-ID i efterhand. |

### Lägg till en taggregel

`POST /agents/{agentId}/tags`

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'
```

**Svar** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }
```

### Ersätt en taggregel

`PUT /agents/{agentId}/tags/{tagId}` — regeln hittas via tagg-id i sökvägen och **ersätts i sin helhet**, inte sammanfogas, så skicka hela regeln istället för bara den del du ändrar. Taggen den pekar på bevaras även om du utelämnar `tag_id`, så en redigering kan inte koppla loss regeln från dess tagg.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'
```

### Ta bort en taggningsregel

`DELETE /agents/{agentId}/tags/{tagId}` — Agenten slutar tillämpa den taggen. Själva taggen, och alla kontakter som redan har den, förblir opåverkade.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"
```

Båda slutpunkterna returnerar `404` när Agenten inte finns **eller** när den inte har någon regel för den taggen.

### Generera en tagguppsättning med AI

`POST /agents/{agentId}/tags/generate` — utformar en hel uppsättning regler (taggnamnen och "tillämpa när…"-formuleringen bakom varje) genom att läsa Agentens egna instruktioner och mål.

| Fält | Beskrivning |
|---|---|
| `mode` | `merge` (standard) behåller reglerna som redan finns på Agenten och lägger till nya. `replace` utformar uppsättningen från grunden. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'
```

**Svar** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }
```

Arbetet körs i bakgrunden. Läs Agenten och bevaka `tag_generation.status`; själva reglerna hamnar i Agentens `tags`. Endast en körning åt gången per Agent (`409` annars), och det förbrukar AI-krediter.

---

## Kunskapskällor

Kunskapskällor är de sidor och dokument som plattformen har läst åt dig. Genom att koppla en till en Agent kan den svara utifrån det innehållet.

**Var käll-id:n kommer ifrån.** Lägg till innehåll med kunskapsbasens slutpunkter — `POST /kb-sources/url` för en sida, `POST /kb-sources/file` för ett dokument, `POST /kb-sources/bulk-import` för en hel webbplats. Dessa returnerar ett `source_id` som du pollar med `GET /kb-sources/{sourceId}` tills det är klart. `POST /kb-sources/url` tar även `autoLinkToAgentId`, vilket kopplar källan till en Agent så snart importen är klar, så att du kan hoppa över kopplingsanropet nedan.

### Koppla kunskapskällor

`POST /agents/{agentId}/kb-sources` — skicka `kb_source_ids` med en lista för att koppla en hel uppsättning i ett anrop (vad du vill ha efter att ha genomsökt en webbplats), eller `kb_source_id` för en enskild källa. Skicka det ena eller det andra. Att koppla något som redan är kopplat ändrar ingenting.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'
```

**Svar** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}
```

### Koppla loss kunskapskällor

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` för en, eller `POST /agents/{agentId}/kb-sources/bulk-remove` med `kb_source_ids` för flera. Massborttagning är en `POST` eftersom listan med id:n skickas i brödtexten.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'
```

Själva källorna raderas inte och förblir tillgängliga för dina andra agenter. Att koppla bort något som inte är kopplat ändrar ingenting.

### Vanliga frågor

Vanliga frågor hanteras via egna slutpunkter och kopplas till en agent därifrån: `POST /faqs/{faqId}/link` med `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`, och `POST /faqs/{faqId}/unlink` för att ta bort den igen. En FAQ kan delas av valfritt antal agenter. Se [FAQs API](faqs.md).

> En FAQ används endast av de agenter den är kopplad till — att skapa en räcker inte i sig.

---

## Verktyg

### Anpassade funktioner

`POST /agents/{agentId}/custom-functions` låter agenten anropa en av dina anpassade funktioner under konversationer. Endast funktioner som tillhör samma konto kan kopplas, och att koppla en som redan är kopplad ändrar ingenting.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'
```

`DELETE /agents/{agentId}/custom-functions/{customFunctionId}` kopplar bort den. Själva funktionen raderas inte och förblir tillgänglig för dina andra agenter.

Hantera själva funktionerna på `/custom-functions` — se [Anpassade funktioner](../ai-automation/custom-functions.md) för vad de är.

### MCP-servrar

En MCP-server är ett färdigt paket med verktyg som din agent kan upptäcka och anropa på egen hand — se [Anslut MCP-servrar till din bot](../ai-automation/mcp-servers.md). Servrar registreras en gång på kontot och kopplas sedan till de agenter som ska använda dem.

> MCP-servrar kräver funktionen **anpassade funktioner** i din plan. Utan den returnerar slutpunkterna för `/mcp-servers` på kontonivå `403`. Att koppla en redan registrerad server till en agent är inte begränsat.

#### Registrera en server

`POST /mcp-servers`

| Fält | Krävs | Beskrivning |
|---|---|---|
| `name` | Ja | En etikett för servern. |
| `url` | Ja | Serverns adress. Måste vara nåbar via det publika internet. |
| `auth_type` | Nej | `header` (standard) för en statisk auth-header, eller `oauth2`. |
| `auth_header_name` | Nej | Header att skicka autentiseringsuppgiften i. Standard är `Authorization`. |
| `auth_header_value` | Nej | Själva autentiseringsuppgiften. Returneras aldrig i något svar. |
| `enabled` | Nej | Huruvida servern är tillgänglig för agenter. Standard är `true`. |
| `enabled_tools` | Nej | Tillåten lista med verktygsnamn. `null` innebär att alla verktyg som servern erbjuder är aktiverade. |
| `tool_policies` | Nej | Gränser per verktyg, nycklade efter verktygsnamn — hur ofta ett verktyg får köras, resultatcachning och en skrivskyddad åsidosättning. Skicka `null` för att rensa alla. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'
```

**Svar** (`201`)

```json
{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}
```

Vid sparning ansluter plattformen till servern och cachar listan över verktyg den erbjuder. **En server som inte kan nås sparas ändå**, med orsaken i `last_error` och en tom verktygslista — så att du kan registrera först och fixa anslutningen efteråt.

En `auth_type` av `oauth2` sparar registreringen med `oauth_connected: false` och inga verktyg: det finns ännu ingen token. Auktorisering av en OAuth-server kräver inloggning via webbläsare och görs från kontrollpanelen, inte via API:et.

#### Lista, uppdatera och ta bort servrar

- `GET /mcp-servers` — varje registrerad server, nyast först, under `servers`.
- `PUT /mcp-servers/{serverId}` — skicka endast det du vill ändra. Att ändra URL eller auth-fält testar anslutningen på nytt och uppdaterar den cachade verktygslistan.
- `DELETE /mcp-servers/{serverId}` — tar bort registreringen och kopplar bort den från varje agent och kampanj som hade den aktiverad.

```bash
curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"
```

**Hemligheter kommer aldrig tillbaka.** Svar bär på `auth_header_value_set` (en `true`/`false`-flagga som anger att ett värde är lagrat) istället för autentiseringsuppgiften, och OAuth-tokens samt klienthemligheter stannar på serversidan. Allt annat returneras: `name`, `url`, `enabled`, `auth_type`, `auth_header_name`, `tools`, `enabled_tools`, `tool_policies`, `oauth_connected`, `tools_cached_at`, `last_connected_at`, `last_error`, `created_at`, `updated_at`.

#### Testa en anslutning

`POST /mcp-servers/test-connection` — ansluter till en server och listar dess verktyg. Två sätt att anropa den:

- med `server_id` — testar den **sparade** konfigurationen och uppdaterar dess cachade verktygslista;
- med en inline `url` (plus `auth_header_name` / `auth_header_value`) — ett test före sparning som inte lagrar någonting.

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'
```

**Svar** (`200`)

```json
{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}
```

Ett anslutningsfel är **inte** ett HTTP-fel — du får ett `200` med `success: false` och ett `error` som beskriver vad som gick fel, så att du kan visa det bredvid fältet som operatören redigerar.

#### Koppla en server till en agent

Att registrera en server ger inte någon agent åtkomst till den. Koppla den:

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'
```

**Svar** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }
```

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` kopplar bort den igen. Själva servern raderas inte och förblir tillgänglig för dina andra agenter. Att koppla eller koppla bort något som redan är i det tillståndet ändrar ingenting.

---

## Mediebibliotek

Mediebiblioteket innehåller filerna som en agent kan skicka under en konversation — en meny, en prislista, ett produktfoto. En agent kan ha högst **50 objekt**.

### Lista media

`GET /agents/{agentId}/media-library`

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"
```

**Svar** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}
```

Objekt som lagras på agenten kommer först, följt av äldre objekt som fortfarande lagras på den kampanj som agenten skapades från; `media_home` (`agent` eller `campaign`) anger vilket som är vilket. Inom varje grupp kommer det nyaste först.

> **`media_url` går ut efter 7 dagar.** Det är nedladdningslänken som skapades när filen laddades upp – betrakta en gammal länk som inaktuell snarare än trasig, och läs in listan på nytt för att få en ny länk.

### Ladda upp media

`POST /agents/{agentId}/media-library` — filen laddas upp inline som base64, upp till **10 MB**. Anropet returneras när filen har lagrats, så räkna med lite längre tid än för en vanlig förfrågan. Observera att denna body använder fältnamn i camelCase.

| Fält | Krävs | Beskrivning |
|---|---|---|
| `base64Data` | Ja | Filinnehåll, base64-kodat, utan ett data-URL-prefix. |
| `mimeType` | Ja | Filens MIME-typ. |
| `fileName` | Ja | Ursprungligt filnamn, används för att namnge den lagrade filen. |
| `title` | Nej | Kort etikett som visas i biblioteket. |
| `description` | Nej | Instruktionen "när ska agenten skicka detta". |
| `sendMessage` | Nej | Föredragen formulering som agenten använder när den skickar objektet. Beskärs till 500 tecken. |
| `maxSendsPerConversation` | Nej | Hur många gånger det får skickas till samma kontakt i en konversation. Standardvärde är `1`. |
| `sendAsVoiceNote` | Nej | Endast ljuduppladdningar — lagra filen som ett WhatsApp-röstmeddelande. Ignoreras för andra filtyper. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'
```

Två saker sker automatiskt: en animerad GIF konverteras till video så att den kan spelas upp i alla kanaler, och plattformen skriver en kort sammanfattning av vad filen faktiskt innehåller så att agenten vet när den passar.

Ett `400` täcker saknade fält, en filtyp som inte stöds, en tom eller för stor fil, samt om gränsen på 50 objekt nås. Ett `403` innebär att mediabiblioteket är avstängt för kontot.

### Uppdatera ett medieobjekt

`PATCH /agents/{agentId}/media-library/{itemId}` — endast metadata. Själva filen kan inte ersättas; ladda upp ett nytt objekt och ta bort det gamla. Denna body använder snake_case: `title`, `description`, `send_message`, `max_sends_per_conversation` (ett icke-negativt heltal, eller `null` för att rensa gränsen).

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'
```

**Svar** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}
```

### Ta bort ett medieobjekt

`DELETE /agents/{agentId}/media-library/{itemId}` — tar bort objektet och dess lagrade fil. Att ta bort ett objekt som redan är borta lyckas och rapporterar `deleted: false`, så anropet är säkert att försöka igen.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"
```

---

## Generera uppföljningsmeddelanden

`POST /agents/{agentId}/template-generation` — skriver agentens uppföljningsmeddelanden åt dig (de påminnelser som skickas när en konversation tystnar), baserat på vad agenten är till för.

| Fält | Beskrivning |
|---|---|
| `type` | `all` (standard) skriver hela uppsättningen. `cold_only` skriver endast meddelanden för kontakter som aldrig svarade. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

Det finns två sätt som detta returneras på, och fältet `target` anger vilket:

- **`target: "agent"` med en `200`** — meddelandena skrevs under samtalet och resultatet finns i `data`. Läs tillbaka dem från agentens `follow_up_config`. Detta är det vanliga fallet.
- **`target: "campaign"` med en `202`** — arbetet köades mot kampanjen som namnges i `campaign_id`. Bevaka den kampanjens `template_generation_status` tills den är klar.

`cold_only` kräver en utgående kampanj och nekas med `409` (`reason: "cold_only_requires_campaign"`) för en agent som saknar en sådan. Ett `403` innebär att automatiska uppföljningar inte är aktiverade för kontot. Detta använder AI-krediter, och ett `400` med `"Insufficient credits."` innebär att kontot har slut på dem.

---

## Dirigera konversationer till en agent

En agent svarar endast på de konversationer som en **ingångspunkt** (Entry Point) skickar till den. Tills en kanal har en sådan lagras fortfarande det första meddelandet från någon du aldrig har pratat med, men ingenting plockar upp det och ingen assistent svarar.

| Vad du vill göra | Anrop |
|---|---|
| Gör en agent till svarare för en hel kanal | `PUT /entry-points/channel-defaults` med `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Lägg till en mer specifik regel (nyckelord, kommentarer, nya följare) | `POST /agents/{agentId}/entry-points` |
| Se reglerna som pekar på en agent | `GET /agents/{agentId}/entry-points` |
| Lämna en kanal utan någon som svarar | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Lista en agents ingångspunkter

`GET /agents/{agentId}/entry-points` — dirigeringsreglerna som skickar konversationer till denna agent, sorterade med de nyaste först. Både nuvarande och avslutade regler returneras; en avslutad regel har `enabled: false`.

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"
```

För kontots övergripande kanalinställningar, inklusive en kanal som avsiktligt ställts in på att ingen ska svara, läs `GET /entry-points/channel-defaults` istället.

### Skapa en ingångspunkt

`POST /agents/{agentId}/entry-points` — agenten i sökvägen vinner alltid, så en regel kan aldrig skapas för en annan agent än den som finns i URL:en.

| `type` | Vad den gör |
|---|---|
| `channel_default` | Agenten svarar på varje ny kontakt på de listade kanalerna. Föredra `PUT /entry-points/channel-defaults` för detta — den avslutar den tidigare svararen åt dig, vilket skapandet av en andra standardregel här inte gör. |
| `keyword` | Agenten tar över när det första meddelandet innehåller ett av `match_config.keywords`. Minst ett nyckelord krävs. |
| `instagram_comment` / `facebook_comment` | Agenten svarar på kommentarer på dina inlägg. Den matchande kanalen måste finnas med i `channels`. |
| `instagram_follower` | Agenten hälsar nya följare välkomna. |

`channels` krävs och anger vilka kanaler regeln omfattar — till exempel `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` eller `custom_channel`. Nya regler är aktiverade om du inte anger något annat.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'
```

**Svar** (`201`)

```json
{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }
```

**Vilken regel vinner när flera kan vara tillämpliga:** en pågående konversation eller en manuell tilldelning behåller den agent den redan har; i övrigt vinner nyckelordsregler över kommentarsregler, som i sin tur vinner över följarregler, och en kanalstandard är den sista utvägen. Huruvida dessa regler avgör något på ett konto rapporteras av `GET /entry-points/routing-status`.

Detta är den korta versionen. Guiden [Entry Points API](entry-points.md) täcker hela stegen, regler för kommentarer och följare, en agent per WhatsApp-nummer samt ändring eller borttagning av en regel. Se [Entry Points](../ai-agents/entry-points.md) för konceptet och [Channels API](channels.md) för att ansluta själva kanalen.

---

## Fel i AI-agent-API:et

Agent-slutpunkter returnerar standardfel-kuvertet:

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| Status | När det inträffar på en Agent-slutpunkt |
|---|---|
| `400` | Ett obligatoriskt fält saknas eller är ogiltigt — en tom uppdateringstext, ett värde utanför en tillåten lista (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), en nyckel som inte är en veckodag i `availability`, ett punktmarkerat fältnamn i `bot-config`, eller ett felaktigt id i sökvägen. |
| `403` | Kontot har inte behörighet att använda en inställning du skickat, du har nått din plans gräns för agenter, eller en funktion som denna slutpunkt behöver (mediabibliotek, uppföljningar, anpassade funktioner för MCP-servrar) är avstängd. En ändring som överskrider den konfigurationsstorlek din plan tillåter nekas med `400`. |
| `404` | Agenten, taggregeln, medieobjektet eller MCP-servern hittades inte — antingen existerar den inte eller så tillhör den ett annat konto. |
| `409` | Något pågår redan eller är i vägen: en optimering eller tagggenerering körs, agenten är fortfarande kopplad till en sändning, startpunkt eller kampanj, eller `cold_only` efterfrågades utan en utgående kampanj. |

De delade koderna som alla slutpunkter kan returnera — `401`, `403` (din plan inkluderar inte API-åtkomst), `429` (hastighetsbegränsning) och `500` — listas med vägledning för återförsök i [Fel & Paginering](errors-and-pagination.md).

> **En notering om utforskaren.** `/agents`-slutpunkterna finns i den publicerade OpenAPI-specifikationen, så du kan bläddra bland deras exakta fält och köra live-förfrågningar i [API-referensen](reference.md). `/mcp-servers`-slutpunkterna på kontonivå finns också i specifikationen, så du kan utforska dem där också.


---

## Relaterat

- [AI-agenter](../ai-agents/ai-agents.md) — vad en agent är, förklarat på enkel svenska.
- [Startpunkter](../ai-agents/entry-points.md) — hur konversationer dirigeras till en agent.
- [FAQ-API](faqs.md) — bygg och länka den kunskap din agent svarar utifrån.
- [Kanal-API](channels.md) — anslut kanalerna som en agent svarar på.
- [Anslut MCP-servrar till din bot](../ai-automation/mcp-servers.md) · [Anpassade funktioner](../ai-automation/custom-functions.md)
- [API-referens](reference.md) — den fullständiga interaktiva slutpunktsutforskaren.