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)
Fel och sidnumrering — se Fel och sidnumrering

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 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 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 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:

{
  "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.

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

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

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

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)

{
  "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.
`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

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

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

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)

{
  "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

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

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

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

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

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

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)

{ "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.

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.

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)

{ "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.

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

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)

{ "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.

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

Svar (201)

{ "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.

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

Svar (200)

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

Blockerad (409)

{
  "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, 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.

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

Svar (200)

{ "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.

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.

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)

{ "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

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)

{ "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.

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.

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.

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)

{ "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.

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)

{
  "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.

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.

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.

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 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. 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.

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)

{
  "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.

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.

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)

{
  "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:

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)

{ "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

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

Svar (200)

{
  "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.

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).

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)

{
  "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.

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.

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.

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.

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)

{ "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 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 för konceptet och Channels API för att ansluta själva kanalen.

Fel i AI-agent-API:et

Agent-slutpunkter returnerar standardfel-kuvertet:

{
  "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.

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. /mcp-servers-slutpunkterna på kontonivå finns också i specifikationen, så du kan utforska dem där också.

Relaterat

AI-agenter — vad en agent är, förklarat på enkel svenska.
Startpunkter — hur konversationer dirigeras till en agent.
FAQ-API — bygg och länka den kunskap din agent svarar utifrån.
Kanal-API — anslut kanalerna som en agent svarar på.
Anslut MCP-servrar till din bot · Anpassade funktioner
API-referens — den fullständiga interaktiva slutpunktsutforskaren.

AI Agents-API #

Hur en agent är uppbyggd #

Agent-objektet #

Lista agenter #

Skapa en Agent #

Hämta en Agent #

Uppdatera en Agent #

Uppdatera botinställningar #

Ställ in aktiva timmar #

Pausa eller återuppta en agent #

Duplicera en agent #

Ta bort en agent #

Utkast: granska ändringar innan de publiceras #

Publicera utkastet #

Förkasta utkastet #

Optimera en agent med AI #

Taggregler #

Lägg till en taggregel #

Ersätt en taggregel #

Ta bort en taggningsregel #

Generera en tagguppsättning med AI #

Kunskapskällor #

Koppla kunskapskällor #

Koppla loss kunskapskällor #

Vanliga frågor #

Verktyg #

Anpassade funktioner #

MCP-servrar #

Registrera en server #

Lista, uppdatera och ta bort servrar #

Testa en anslutning #

Koppla en server till en agent #

Mediebibliotek #

Lista media #

Ladda upp media #

Uppdatera ett medieobjekt #

Ta bort ett medieobjekt #

Generera uppföljningsmeddelanden #

Dirigera konversationer till en agent #

Lista en agents ingångspunkter #

Skapa en ingångspunkt #

Fel i AI-agent-API:et #

Relaterat #

AI Agents-API

Hur en agent är uppbyggd

Agent-objektet

Lista agenter

Skapa en Agent

Hämta en Agent

Uppdatera en Agent

Uppdatera botinställningar

Ställ in aktiva timmar

Pausa eller återuppta en agent

Duplicera en agent

Ta bort en agent

Utkast: granska ändringar innan de publiceras

Publicera utkastet

Förkasta utkastet

Optimera en agent med AI

Taggregler

Lägg till en taggregel

Ersätt en taggregel

Ta bort en taggningsregel

Generera en tagguppsättning med AI

Kunskapskällor

Koppla kunskapskällor

Koppla loss kunskapskällor

Vanliga frågor

Verktyg

Anpassade funktioner

MCP-servrar

Registrera en server

Lista, uppdatera och ta bort servrar

Testa en anslutning

Koppla en server till en agent

Mediebibliotek

Lista media

Ladda upp media

Uppdatera ett medieobjekt

Ta bort ett medieobjekt

Generera uppföljningsmeddelanden

Dirigera konversationer till en agent

Lista en agents ingångspunkter

Skapa en ingångspunkt

Fel i AI-agent-API:et

Relaterat