Connecting a Custom API
Connect any system with a REST API to Symbi — your agents call the endpoints you allow, and the system can post to the agent's own webhook URL.
What Custom API Enables
Custom API is the generic connector for any system that has its own REST API and no dedicated Symbi pack — an internal tool, a smaller SaaS product, anything with a base URL and some endpoints. Each system you connect ("BookIt", "Our Warehouse API") gets its own tile, shown as "<name> · Custom API" — Custom API is not one connection, it is one tile per system you add.
A Custom API connection does two things once it is wired into an agent:
- Outbound calls — an agent can call specific endpoints you define, each becoming a tool named
http_<slug> - Inbound webhook — the connected system can post to the agent's own secret URL, and each post becomes a task for the agent to handle
Both halves are set up through the agent builder chat, not a settings form — the chat asks for exactly the connection to use, then builds the tool or webhook from what you describe.
Connect Your System
- Open Settings → Connectors and click the Custom API tile
- Click Configure Custom API
- Enter:
- System name — shown on the tile, e.g. "BookIt"
- Base URL — e.g.
https://api.bookit.no/v2. Agents can only call this host; addresses on your own private network cannot be reached - How Symbi signs in — one of:
- API key in a header — you also name the header (e.g.
X-Api-Key) - Bearer token
- Username and password
- No key — for a public API that needs no credential
- API key in a header — you also name the header (e.g.
- Click Connect
Only Owner and Admin users can configure connectors. The key, token, or password is stored encrypted; agents never see it directly.
Add Endpoints Through the Agent Builder Chat
A fresh connection has no endpoints yet — connecting only stores the base URL and credential. To give an agent a specific call, describe it to the agent builder chat: which connection, a short slug (the tool becomes http_<slug>), what the call does, the HTTP method (GET, POST, PUT, PATCH, or DELETE), the path after the base URL (e.g. /bookings/{bookingId}, with {name} marking a path parameter), and the parameters the agent may fill in — each one as a path, query, or body value. Anything not declared this way cannot be sent.
Each endpoint gets a review group — how carefully Symbi treats calls to it. You can state one, or leave it to the default: a GET call defaults to read, and any other method defaults to produce, which is held for review unless the agent is set to a more autonomous mode.
The endpoint takes effect the next time the agent is published.
Set Up an Incoming Webhook
The same chat can give the agent a generic incoming webhook: a secret URL that the connected system posts to, with each post becoming a task. Describe to the chat which connection is sending, what the agent should do with each delivery (the posted body is its input), and optionally:
- a field in the payload that identifies a delivery (e.g.
booking.id), so a repeated post with the same value is treated as the same task rather than a new one - an HMAC signature header the sender adds, if the sending system supports signing
The chat never shows you or the model the webhook URL or its signing secret directly. Once set up, both appear on the connection's own page (Settings → Connectors → Custom API → <system>), under Incoming webhooks — masked by default, with Show and Copy buttons, and a Rotate URL button that invalidates the current URL at once (paste the new one into the sending system afterwards). The webhook starts accepting posts once the agent is published and live; a draft or paused agent's webhook URL exists but takes no deliveries yet.
Limitations
- Beta — Custom API is still being extended; expect its connect flow and endpoint tooling to change
- Not a trigger through bindings — a Custom API connection cannot be bound to an agent as an input/output/human-in-the-loop resource. The two ways it reaches an agent are the
http_tools described above and the agent's own webhook URL - No auto-discovery — there is nothing to "find more resources" on; every endpoint is defined explicitly through the chat
- Company integration — not available for the Personal Assistant
What's Next?
- Describe the endpoints and webhook you need in the agent builder chat, then publish the agent to activate them
- Set review groups deliberately for any
produceendpoint — see tuning your agent's behavior - Review inbound deliveries and outbound calls in the Operation Center
Hva Custom API muliggjør
Custom API er den generiske koblingen for et hvilket som helst system med sitt eget REST-API og ingen dedikert Symbi-pakke — et internt verktøy, et mindre SaaS-produkt, alt med en base-URL og noen endepunkter. Hvert system du kobler til ("BookIt", "Vårt lagersystem") får sitt eget kort, vist som "<navn> · Custom API" — Custom API er ikke én kobling, det er ett kort per system du legger til.
En Custom API-kobling gjør to ting når den er koblet til en agent:
- Utgående kall — en agent kan kalle bestemte endepunkter du definerer, hvert av dem blir et verktøy med navnet
http_<slug> - Innkommende webhook — det tilkoblede systemet kan poste til agentens egen hemmelige URL, og hver post blir en oppgave agenten skal håndtere
Begge deler settes opp gjennom agentbyggerchatten, ikke et innstillingsskjema — chatten spør etter nøyaktig hvilken kobling som skal brukes, og bygger deretter verktøyet eller webhooken fra det du beskriver.
Koble til systemet ditt
- Åpne Settings → Connectors og klikk på Custom API-kortet
- Klikk Configure Custom API
- Fyll inn:
- System name — vises på kortet, f.eks. "BookIt"
- Base URL — f.eks.
https://api.bookit.no/v2. Agenter kan bare kalle denne verten; adresser på ditt eget private nettverk kan ikke nås - How Symbi signs in — en av:
- API key in a header — du oppgir også headernavnet (f.eks.
X-Api-Key) - Bearer token
- Username and password
- No key — for et offentlig API som ikke krever en nøkkel
- API key in a header — du oppgir også headernavnet (f.eks.
- Klikk Connect
Kun Owner- og Admin-brukere kan konfigurere koblinger. Nøkkelen, tokenet eller passordet lagres kryptert; agenter ser det aldri direkte.
Legg til endepunkter gjennom agentbyggerchatten
En ny kobling har ingen endepunkter ennå — å koble til lagrer bare base-URL-en og påloggingsinformasjonen. For å gi en agent et bestemt kall, beskriv det til agentbyggerchatten: hvilken kobling, en kort slug (verktøyet blir http_<slug>), hva kallet gjør, HTTP-metoden (GET, POST, PUT, PATCH eller DELETE), stien etter base-URL-en (f.eks. /bookings/{bookingId}, der {navn} markerer en stiparameter), og parameterne agenten kan fylle ut — hver som en sti-, query- eller body-verdi. Alt som ikke er deklarert slik kan ikke sendes.
Hvert endepunkt får en review-gruppe — hvor nøye Symbi behandler kall til det. Du kan oppgi en selv, eller la standarden gjelde: et GET-kall får som standard read, og alle andre metoder får produce, som holdes for gjennomgang med mindre agenten er satt til en mer autonom modus.
Endepunktet trer i kraft neste gang agenten publiseres.
Sett opp en innkommende webhook
Den samme chatten kan gi agenten en generisk innkommende webhook: en hemmelig URL det tilkoblede systemet poster til, der hver post blir en oppgave. Beskriv til chatten hvilken kobling som sender, hva agenten skal gjøre med hver levering (den posterte kroppen er dens input), og eventuelt:
- et felt i innholdet som identifiserer en levering (f.eks.
booking.id), slik at en gjentatt post med samme verdi behandles som samme oppgave i stedet for en ny - en HMAC-signaturheader avsenderen legger til, hvis det sendende systemet støtter signering
Chatten viser aldri deg eller modellen webhook-URL-en eller signeringshemmeligheten direkte. Når den er satt opp, vises begge på koblingens egen side (Settings → Connectors → Custom API → <system>), under Incoming webhooks — maskert som standard, med Show- og Copy-knapper, og en Rotate URL-knapp som gjør den nåværende URL-en ugyldig med én gang (lim inn den nye i det sendende systemet etterpå). Webhooken begynner å ta imot poster først når agenten er publisert og live; en agent i utkast eller på pause har en webhook-URL som finnes, men som ikke tar imot leveranser ennå.
Begrensninger
- Beta — Custom API er fortsatt under utvikling; forvent at tilkoblingsflyten og endepunktverktøyene endres
- Ikke en trigger gjennom bindinger — en Custom API-kobling kan ikke bindes til en agent som en input-/output-/menneske-i-loopen-ressurs. De to måtene den når en agent er
http_-verktøyene beskrevet over og agentens egen webhook-URL - Ingen automatisk oppdagelse — det er ingenting å "finn flere ressurser" på; hvert endepunkt defineres eksplisitt gjennom chatten
- Bedriftsintegrasjon — ikke tilgjengelig for Personlig Assistent
Hva nå?
- Beskriv endepunktene og webhooken du behøver i agentbyggerchatten, og publiser agenten for å aktivere dem
- Sett review-grupper med omhu for ethvert
produce-endepunkt — se innstilling av agentens oppførsel - Gå gjennom innkommende leveranser og utgående kall i Operation Center