AI Agents API #

Een AI Agent is het brein achter je bot: de instructies, persoonlijkheid, taal, kennis en tools. Je bouwt een Agent één keer en stuurt vervolgens verkeer ernaartoe. Deze gids behandelt alles wat je met een Agent kunt doen via de API — aanmaken, configureren, voorzien van kennis en tools, concepten beoordelen en gesprekken ernaartoe routeren.

• Basis-URL — https://api.youraiconnector.com/v1
• Authenticatie — uw API-sleutel (zie Authenticatie)
• Fouten & paginering — zie Fouten & Paginering

Alle onderstaande voorbeelden tonen de ?apiKey= query-vorm in cURL en de X-API-Key header in JavaScript en Python — beide werken op elk eindpunt.

Als je nieuw bent met het concept Agents, lees dan eerst AI Agents.

Hoe een Agent in elkaar zit #

Vier onderdelen worden afzonderlijk beheerd, en het is handig om te weten wat wat is voordat je begint:

Een nieuwe Agent antwoordt niemand totdat je ernaartoe routeert. Het aanmaken van een Agent plaatst deze niet op een kanaal. Dat is de stap die de meeste integraties missen — zie Gesprekken routeren naar een Agent aan het einde van deze pagina.

Het Agent-object #

Een volledig Agent-document is groot — enkele honderden kilobytes, voornamelijk de lijst met veelgestelde vragen, kennisbronnen en eventuele pagina-inhoud die van je website is gelezen. Daarom geeft het opvragen van een lijst een korte samenvattingsrij per Agent terug:

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

Het volledige document voegt al het andere toe: instructions, rules, personality, availability, follow_up_config, de gekoppelde lijsten met veelgestelde vragen en kennisbronnen, de gegenereerde tekstblokken en eventuele uitvoeringsstatus (tag_generation, optimize_run).

Sommige antwoorden bevatten ook substrate_campaign_id. Dit is een intern record dat wordt bijgehouden op oudere accounts; je hoeft er nooit actie op te ondernemen, en op nieuwere accounts is het null of afwezig.

Agents weergeven #

GET /agents — elke Agent op het account, nieuwste eerst.

Dit eindpunt is niet gepagineerd. Standaard wordt elke Agent geretourneerd met zijn volledige configuratie, wat zwaar is: een enkele Agent kan 580 KB bereiken en een account met 64 Agents meer dan 3 MB. Geef view=summary door voor een korte rij per Agent, en lees vervolgens degene die je wilt met Get an Agent.

Queryparameters

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

Antwoord (200)

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

Een Agent aanmaken #

POST /agents — alleen name is echt nodig; stuur alle configuratie die je al kent mee. Een nieuwe Agent is standaard actief.

Aanvraagvelden (allemaal optioneel behalve name)

Een Agent bouwen vanaf je website. Voeg scrape_urls toe en het platform leest die pagina’s en schrijft de instructies voor je. Het antwoord vertelt je of die generatie is gestart, zodat je weet of je de Agent moet pollen voor de voortgang.

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"])

Antwoord (201)

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

agent_generation_queued is true wanneer het platform is begonnen met het schrijven van de instructies op basis van de pagina’s die je hebt opgegeven.

Een 400 betekent dat de body geen JSON-object was, een veld werd geweigerd, of de Agent de configuratiegrootte overschrijdt die je abonnement toestaat. Een 403 betekent dat het account niet is toegestaan om een van de verzonden instellingen te gebruiken — bijvoorbeeld een AI-niveau dat de accountprovider niet heeft toegekend.

Een Agent ophalen #

GET /agents/{agentId}

Geef fields door met een door komma’s gescheiden lijst om alleen terug te krijgen wat je nodig hebt, bijvoorbeeld fields=name,active,goal. De id is altijd inbegrepen, en namen die niet bestaan op de Agent worden genegeerd in plaats van geweigerd. Laat dit weg om het volledige document te krijgen.

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

Een Agent die niet bestaat in je account retourneert 404.

Een Agent bijwerken #

PUT /agents/{agentId} — stuur alleen de velden die je wilt wijzigen; al het andere blijft ongewijzigd.

Geneste instellingen kunnen per blad worden aangepast met een punt-sleutel, dus "availability.monday" wijzigt alleen maandag en laat de rest van de week ongemoeid.

Opmerkingen

• Om te wijzigen voor welk boekbaar evenementtype de Agent boekingen maakt, stuur event_id (de id van het evenement, of null om dit te wissen). Stuur event_ids met een array om er meerdere tegelijk te koppelen — de eerste wordt de primaire en [] ontkoppelt alles. event_id en event_ids sluiten elkaar uit, en het veld event zelf kan niet direct worden beschreven.
• enable_bookings moet een echte boolean zijn, en booking_provider moet een van default, zenchef, formitable zijn.
• Eigendoms- en identiteitsvelden worden genegeerd, evenals de interne uitvoeringsstatus (voortgang van generatie en optimalisatie).
• Routering wordt hier niet ingesteld. Gebruik PUT /entry-points/channel-defaults om de Agent de beantwoorder voor een kanaal te maken, POST /agents/{agentId}/entry-points voor trefwoord- en commentaarregels, en PATCH /agents/{agentId}/active om deze te pauzeren of te hervatten.

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"},
)

Antwoord (200)

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

Een lege body retourneert 400 met "No fields to update".

Botinstellingen bijwerken #

PUT /agents/{agentId}/bot-config — de specifieke manier om alleen de gespreksinstellingen te wijzigen.

Een Agent heeft geen afzonderlijke bot-sectie: de instellingen staan direct op de Agent, dus de veldnamen hier zijn dezelfde als die je naar PUT /agents/{agentId} zou sturen. Dit eindpunt bestaat als de veilige, gerichte manier om er een aantal te wijzigen. Ten minste één veld is vereist.

Veldnamen moeten hier eenvoudige namen zijn — letters, cijfers, underscores en koppeltekens. Punt-paden worden op dit eindpunt niet geaccepteerd (in tegenstelling tot PUT /agents/{agentId}), dus bot.goal wordt geweigerd met een 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" }'

Lange tekst telt mee voor de configuratiegrootte die je abonnement toestaat, dus een zeer grote instructieset kan worden geweigerd met een 400.

Actieve uren instellen #

PUT /agents/{agentId}/active-hours — de uren waarin de Agent automatisch antwoordt. Buiten die vensters blijft deze stil.

Stuur een availability object met de weekdag als sleutel (monday tot en met sunday). Elke dag neemt één tijdvenster of een lijst met vensters aan, in 24-uurs HH:MM notatie. Dagen die je weglaat behouden hun huidige instelling, en elke sleutel die geen weekdag is, wordt geweigerd — zodat een typefout niet ongemerkt niets doet.

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" }
      ]
    }
  }'

Antwoord (200)

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

Een onjuiste weekdagsleutel retourneert 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Een Agent pauzeren of hervatten #

PATCH /agents/{agentId}/active — schakelt de Agent in of uit. Een gepauzeerde Agent behoudt al zijn configuratie, maar stopt onmiddellijk met antwoorden; hervatten heeft direct effect.

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 }),
});

Antwoord (200)

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

active moet een echte boolean zijn — al het andere retourneert 400 met "active (boolean) is required".

Een Agent dupliceren #

POST /agents/{agentId}/duplicate — maakt een kopie met behoud van de configuratie. De kopie verstuurt niets totdat u er een kanaal of Entry Point naar verwijst.

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

Antwoord (201)

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

Een duplicaat telt voor het Agent-quotum van uw abonnement net als het maken van een nieuwe, dus het wordt geweigerd met 403 wanneer het account zijn limiet heeft bereikt.

Een Agent verwijderen #

DELETE /agents/{agentId}

Het verwijderen wordt geweigerd zolang de Agent nog gekoppeld is aan iets dat zonder de Agent niet zou werken — een uitzending, een Entry Point of (bij oudere accounts) een campagne. Het antwoord bevat een lijst met wat de Agent vasthoudt, zodat u deze eerst kunt loskoppelen en het opnieuw kunt proberen.

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

Antwoord (200)

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

Geblokkeerd (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": []
}

Concepten: wijzigingen controleren voordat ze live gaan #

Bewerkingen die in de editor zijn gemaakt, en elke herschreven tekst die is geproduceerd door Optimaliseren met AI, worden bewaard als een ongepubliceerd concept totdat u ze publiceert. De live Agent blijft tot die tijd antwoorden met de huidige configuratie.

Het concept publiceren #

POST /agents/{agentId}/publish-draft — verplaatst het concept naar de live configuratie en wist het concept in dezelfde stap.

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

Antwoord (200)

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

published_keys geeft een lijst weer van de instellingen die van het concept naar de live Agent zijn verplaatst, zodat u kunt laten zien wat er is gewijzigd.

Controleer of er een concept bestaat voordat u dit aanroept. Het publiceren van een Agent die geen concept heeft, is geen ondersteunde aanroep en resulteert momenteel in een 500 met een algemeen bericht, niet een specifiek bericht. Gebruik hieronder verwijderen om een concept weg te gooien.

Verwerp het concept #

POST /agents/{agentId}/discard-draft — gooit het concept weg en laat de live configuratie precies zoals deze is. Veilig om aan te roepen wanneer er geen concept is; er gebeurt niets.

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

Een Agent optimaliseren met AI #

POST /agents/{agentId}/optimize — herschrijft de configuratie van de Agent op basis van uw feedback (“hij blijft kortingen aanbieden”, “antwoorden zijn te lang”) en slaat de herschreven versie op als concept in plaats van deze direct live te zetten.

Stuur ofwel user_feedback (een eenvoudige instructie) of, wanneer u reageert op een specifiek slecht antwoord, thumbs_down_feedback samen met het betreffende thumbs_down_message. Minstens één van de twee moet tekst bevatten.

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." }'

Antwoord (202)

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

Het werk wordt op de achtergrond uitgevoerd en de aanroep keert direct terug. Lees de Agent met GET /agents/{agentId} en houd optimize_run.status in de gaten; zodra deze weer op Draft staat, staat de herschreven versie klaar als het concept van de Agent. Controleer deze en publiceer of verwerp het concept vervolgens.

Slechts één uitvoering tegelijk per Agent — een tweede aanroep terwijl er al een bezig is, retourneert 409. Dit verbruikt AI-credits.

Tagregels #

Een tagregel is een tag plus een beschrijving van wanneer deze van toepassing is. Tijdens een gesprek leest de Agent die beschrijving en voorziet de contactpersoon van een tag wanneer dit past; zo worden door tags aangestuurde automatiseringen geactiveerd.

Het regelobject

Een tagregel toevoegen #

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
    }
  }'

Antwoord (200)

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

Een tagregel vervangen #

PUT /agents/{agentId}/tags/{tagId} — de regel wordt gevonden op basis van de tag-id in het pad en in zijn geheel vervangen, niet samengevoegd. Stuur dus de volledige regel in plaats van alleen het gedeelte dat u wijzigt. De tag waarnaar wordt verwezen blijft behouden, zelfs als u tag_id weglaat, dus een bewerking kan de regel niet loskoppelen van de tag.

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." } }'

Een tag-regel verwijderen #

DELETE /agents/{agentId}/tags/{tagId} — de Agent stopt met het toepassen van die tag. De tag zelf, en alle contacten die deze al hebben, blijven ongewijzigd.

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

Beide eindpunten retourneren 404 wanneer de Agent niet bestaat of wanneer deze geen regel heeft voor die tag.

Een tag-set genereren met AI #

POST /agents/{agentId}/tags/generate — ontwerpt een volledige set regels (de tag-namen en de “pas toe wanneer…”-formulering achter elke regel) door de eigen instructies en het doel van de Agent te lezen.

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

Antwoord (202)

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

Het werk wordt op de achtergrond uitgevoerd. Lees de Agent en houd tag_generation.status in de gaten; de regels zelf komen terecht in de tags van de Agent. Slechts één uitvoering tegelijk per Agent (409 anders), en het verbruikt AI-credits.

Kennisbronnen #

Kennisbronnen zijn de pagina’s en documenten die het platform voor u heeft gelezen. Door er een aan een Agent te koppelen, kan deze antwoorden op basis van die inhoud.

Waar bron-id’s vandaan komen. Voeg inhoud toe met de kennisbank-eindpunten — POST /kb-sources/url voor een pagina, POST /kb-sources/file voor een document, POST /kb-sources/bulk-import voor een hele site. Deze retourneren een source_id die u pollt met GET /kb-sources/{sourceId} totdat deze gereed is. POST /kb-sources/url accepteert ook autoLinkToAgentId, waarmee de bron direct aan een Agent wordt gekoppeld zodra het importeren is voltooid, zodat u de onderstaande koppelingsaanroep kunt overslaan.

Kennisbronnen koppelen #

POST /agents/{agentId}/kb-sources — stuur kb_source_ids met een lijst om een hele set in één aanroep te koppelen (wat u wilt na het crawlen van een site), of kb_source_id voor een enkele bron. Stuur de een of de ander. Het koppelen van iets dat al gekoppeld is, verandert niets.

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"] }'

Antwoord (200)

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

Kennisbronnen ontkoppelen #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} voor één, of POST /agents/{agentId}/kb-sources/bulk-remove met kb_source_ids voor meerdere. Bulkverwijdering is een POST omdat de lijst met id’s in de body wordt meegestuurd.

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"] }'

De bronnen zelf worden niet verwijderd en blijven beschikbaar voor je andere Agents. Het loskoppelen van iets dat niet is gekoppeld, verandert niets.

Veelgestelde vragen #

Veelgestelde vragen (FAQ’s) worden beheerd op hun eigen eindpunten en vanaf daar gekoppeld aan een Agent: POST /faqs/{faqId}/link met { "agent_id": "ag7HkQ2ZpLxR3mNb" }, en POST /faqs/{faqId}/unlink om het weer te verwijderen. Een FAQ kan door een willekeurig aantal Agents worden gedeeld. Zie de FAQs API.

Een FAQ wordt alleen gebruikt door de Agents waaraan deze is gekoppeld — het aanmaken ervan is op zichzelf niet voldoende.

Tools #

Aangepaste functies #

POST /agents/{agentId}/custom-functions stelt de Agent in staat om tijdens gesprekken een van je aangepaste functies aan te roepen. Alleen functies die bij hetzelfde account horen, kunnen worden gekoppeld, en het koppelen van een functie die al is gekoppeld, verandert niets.

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} koppelt deze los. De functie zelf wordt niet verwijderd en blijft beschikbaar voor je andere Agents.

Beheer de functies zelf op /custom-functions — zie Aangepaste functies voor wat dit inhoudt.

MCP-servers #

Een MCP-server is een kant-en-klaar pakket met tools die je Agent zelf kan ontdekken en aanroepen — zie MCP-servers verbinden met je bot. Servers worden eenmalig geregistreerd op het account en vervolgens gekoppeld aan de Agents die ze moeten gebruiken.

MCP-servers vereisen de functie aangepaste functies in je abonnement. Zonder deze functie retourneren de /mcp-servers-eindpunten op accountniveau 403. Het koppelen van een reeds geregistreerde server aan een Agent is niet beperkt.

Een server registreren #

POST /mcp-servers

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"
  }'

Antwoord (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", "...": "..." }
}

Bij het opslaan maakt het platform verbinding met de server en cachet de lijst met tools die deze aanbiedt. Een server die niet bereikbaar is, wordt toch opgeslagen, met de reden in last_error en een lege tool-lijst — zodat u eerst kunt registreren en de connectiviteit later kunt herstellen.

Een auth_type van oauth2 slaat de registratie op met oauth_connected: false en zonder tools: er is nog geen token. Het autoriseren van een OAuth-server vereist een browser-aanmelding en wordt gedaan via het dashboard, niet via de API.

Servers weergeven, bijwerken en verwijderen #

• GET /mcp-servers — elke geregistreerde server, nieuwste eerst, onder servers.
• PUT /mcp-servers/{serverId} — stuur alleen wat u wilt wijzigen. Het wijzigen van de URL of de auth-velden test de verbinding opnieuw en ververst de gecachte tool-lijst.
• DELETE /mcp-servers/{serverId} — verwijdert de registratie en ontkoppelt deze van elke Agent en campagne waarvoor deze was ingeschakeld.

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

Geheimen komen nooit terug. Antwoorden bevatten auth_header_value_set (een true/false-vlag die aangeeft dat een waarde is opgeslagen) in plaats van de inloggegevens, en OAuth-tokens en client-geheimen blijven aan de serverzijde. Al het andere wordt geretourneerd: 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.

Een verbinding testen #

POST /mcp-servers/test-connection — maakt verbinding met een server en somt de tools op. Twee manieren om dit aan te roepen:

• met server_id — test de opgeslagen configuratie en ververst de gecachte tool-lijst;
• met een inline url (plus auth_header_name / auth_header_value) — een test vóór het opslaan die niets opslaat.

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" }'

Antwoord (200)

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

Een verbindingsfout is geen HTTP-fout — u krijgt een 200 met success: false en een error die beschrijft wat er misging, zodat u dit kunt tonen naast het veld dat de operator aan het bewerken is.

Een server koppelen aan een Agent #

Het registreren van een server geeft een Agent er nog geen toegang toe. Koppel deze:

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" }'

Antwoord (200)

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

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} ontkoppelt deze weer. De server zelf wordt niet verwijderd en blijft beschikbaar voor uw andere Agents. Het koppelen of ontkoppelen van iets dat zich al in die status bevindt, verandert niets.

Mediabibliotheek #

De mediabibliotheek bevat de bestanden die een Agent tijdens een gesprek kan verzenden — een menu, een prijslijst, een productfoto. Een Agent kan maximaal 50 items bevatten.

Media weergeven #

GET /agents/{agentId}/media-library

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

Antwoord (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
    }
  ]
}

Items die op de Agent zijn opgeslagen komen eerst, gevolgd door oudere items die nog steeds zijn opgeslagen in de campagne waarvoor de Agent is gebouwd; media_home (agent of campaign) geeft aan welke wat is. Binnen elke groep staat het nieuwste item bovenaan.

media_url verloopt na 7 dagen. Dit is de downloadlink die is aangemaakt toen het bestand werd geüpload — beschouw een oude link als verouderd in plaats van defect, en lees de lijst opnieuw om een nieuwe link te verkrijgen.

Media uploaden #

POST /agents/{agentId}/media-library — het bestand wordt inline geüpload als base64, tot 10 MB. De aanroep keert terug zodra het bestand is opgeslagen, dus houd rekening met een iets langere verwerkingstijd dan bij een normaal verzoek. Let op: deze body gebruikt camelCase-veldnamen.

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
  }'

Er gebeuren automatisch twee dingen: een geanimeerde GIF wordt geconverteerd naar video zodat deze op elk kanaal wordt afgespeeld, en het platform schrijft een korte samenvatting van wat er daadwerkelijk in het bestand staat, zodat de Agent weet wanneer het past.

Een 400 dekt ontbrekende velden, een niet-ondersteund bestandstype, een leeg of te groot bestand, en het bereiken van de limiet van 50 items. Een 403 betekent dat de mediabibliotheek is uitgeschakeld voor het account.

Een media-item bijwerken #

PATCH /agents/{agentId}/media-library/{itemId} — alleen metadata. Het bestand zelf kan niet worden vervangen; upload een nieuw item en verwijder het oude. Deze body gebruikt snake_case: title, description, send_message, max_sends_per_conversation (een niet-negatief geheel getal, of null om de limiet te wissen).

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 }'

Antwoord (200)

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

Een media-item verwijderen #

DELETE /agents/{agentId}/media-library/{itemId} — verwijdert het item en het bijbehorende opgeslagen bestand. Het verwijderen van een item dat al weg is, slaagt en rapporteert deleted: false, dus de aanroep is veilig om opnieuw te proberen.

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

Follow-upberichten genereren #

POST /agents/{agentId}/template-generation — schrijft de follow-upberichten van de Agent voor u (de herinneringen die worden verzonden wanneer een gesprek stilvalt), gebaseerd op het doel van de Agent.

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

Er zijn twee manieren waarop dit terugkomt, en het target-veld vertelt je welke:

• target: "agent" met een 200 — de berichten zijn tijdens het gesprek geschreven en het resultaat staat in data. Lees ze terug vanuit de follow_up_config van de Agent. Dit is het gebruikelijke geval.
• target: "campaign" met een 202 — het werk is in de wachtrij geplaatst voor de campagne die wordt genoemd in campaign_id. Houd de template_generation_status van die campagne in de gaten totdat deze is voltooid.

cold_only heeft een uitgaande campagne nodig en wordt geweigerd met 409 (reason: "cold_only_requires_campaign") bij een Agent die er geen heeft. Een 403 betekent dat automatische follow-ups niet zijn ingeschakeld voor het account. Dit verbruikt AI-credits, en een 400 met "Insufficient credits." betekent dat het account geen credits meer heeft.

Gesprekken doorsturen naar een Agent #

Een Agent beantwoordt alleen de gesprekken die door een Toegangspunt worden verzonden. Totdat een kanaal er een heeft, wordt een eerste bericht van iemand met wie je nog nooit hebt gesproken wel opgeslagen, maar wordt het door niemand opgepikt en antwoordt er geen assistent.

Toegangspunten van een Agent weergeven #

GET /agents/{agentId}/entry-points — de routeringsregels die gesprekken naar deze Agent sturen, nieuwste eerst. Zowel huidige als ingetrokken regels komen terug; een ingetrokken regel heeft enabled: false.

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

Lees voor de standaardinstellingen van het kanaal voor het hele account, inclusief een kanaal dat bewust op ‘niemand’ is ingesteld, in plaats daarvan GET /entry-points/channel-defaults.

Een toegangspunt maken #

POST /agents/{agentId}/entry-points — de Agent in het pad wint altijd, dus er kan nooit een regel worden gemaakt voor een andere Agent dan degene in de URL.

channels is vereist en geeft aan welke kanalen de regel dekt — bijvoorbeeld whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget of custom_channel. Nieuwe regels zijn ingeschakeld, tenzij je anders aangeeft.

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"] }
  }'

Antwoord (201)

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

Welke regel wint als er meerdere mogelijk zijn: een lopend gesprek of een handmatige toewijzing behoudt de Agent die het al heeft; anders gaan trefwoordregels voor op opmerkingsregels, die weer voorgaan op volgersregels, en een kanaalstandaard is de laatste redmiddel. Of deze regels al iets bepalen op een account wordt gerapporteerd door GET /entry-points/routing-status.

Dit is de korte versie. De handleiding voor de Entry Points API behandelt de volledige regels voor ladder, opmerkingen en volgers, één Agent per WhatsApp-nummer, en het wijzigen of verwijderen van een regel. Zie Entry Points voor het concept, en de Channels API voor het verbinden van het kanaal zelf.

AI Agents API-fouten #

Agent-endpoints retourneren de standaard fouten-envelop:

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

De gedeelde codes die elk endpoint kan retourneren — 401, 403 (uw abonnement bevat geen API-toegang), 429 (snelheidslimiet) en 500 — worden vermeld met richtlijnen voor opnieuw proberen in Fouten & Paginering.

Een opmerking over de explorer. De /agents-endpoints staan in de gepubliceerde OpenAPI-specificatie, dus u kunt hun exacte velden bekijken en live verzoeken uitvoeren in de API-referentie. De /mcp-servers-endpoints op accountniveau staan ook in de specificatie, dus u kunt ze daar ook verkennen.

Gerelateerd #

• AI Agents — wat een Agent is, in begrijpelijke taal.
• Toegangspunten — hoe gesprekken naar een Agent worden gerouteerd.
• FAQs API — bouw en koppel de kennis waar uw Agent antwoorden uit haalt.
• Channels API — verbind de kanalen waarop een Agent antwoordt.
• Verbind MCP-servers met uw bot · Aangepaste functies
• API-referentie — de volledige interactieve endpoint-explorer.