REST API
Agents, chat, conversations, knowledge, websites, prompts, workflows, runs, roles and more under /api/v1, with an interactive reference that includes a workflow authoring guide and step catalogue.
No hidden private API. Build on what we build on.
The Gecko console runs on the same public REST API and TypeScript SDK you get. Anything the interface can do, your own systems can do — with scoped tokens, open standards and portable definitions.
REST/api/v1
OpenAPI 3generated spec
MCPopen tool standard
JSONportable workflows
// TypeScript SDK — the same client the console uses
import GeckoAI from '@geckolabs/geckoai-sdk-ts';
const gecko = new GeckoAI({
apiKey: process.env.GECKO_API_KEY,
baseURL: 'https://your-region.api.example',
});
// Ask an agent — guardrails, tools and tracing apply
const reply = await gecko.chat.create(agentId, {
message: 'When do applications close?',
participant: { email: 'applicant@example.com' },
});
// Queue a run of the published workflow version
const run = await gecko.workflows.createRun(workflowId, {
input: { enquiryId: 'ENQ-20931' },
});
API & SDK
One contract for the console and for you.
A tenant-scoped REST API with an OpenAPI 3 spec generated from the running service — so the documentation can’t drift from the code.
TypeScript SDK
@geckolabs/geckoai-sdk-ts is generated from the same spec, with resource-style methods — list, get, create, update — plus streaming chat.
Any language
Generate clients for Python, C#, Java or anything else from the OpenAPI spec using the tooling your team already trusts.
Anything the console can do, an institution’s own systems can do — because the console is just another API client.
Machine access
API tokens that behave like policy.
Create tokens for each integration with the narrowest scope that works. They inherit the controls your people already have — and can be held to stricter ones.
- Scope presets — read only, chatbot or full access — or pick individual permissions
- Permission ceiling — a token can never exceed its creator’s role, enforced server-side
- Expiry, revocation and last-used tracking; stored only as a hash and shown once
- Attach guardrail groups so a public chatbot key carries stricter rules than staff
Website chatbotChatbot · expires in 84 days · used 2 min agoActive
Student portal integrationCustom · expires in 12 days · used 1 h agoExpiring
Reporting exportRead only · expires in 180 days · used yesterdayActive
Events in and out
Trigger work from any system.
Every workflow has its own unguessable inbound webhook URL. Post JSON from your CRM, SIS, ticketing tool or form builder and it becomes $.input for the run. Going the other way, Webhook steps send JSON to your endpoints.
- Inbound — one URL per workflow; no token to leak into third-party config
- Outbound — POST, PUT or PATCH with custom headers, through a mandatory egress proxy in production
- Guarded — outbound requests are blocked from reaching private and reserved address ranges
# Start a workflow run from any system
curl -X POST \
https://your-region.api.example/api/v1/webhooks/workflows/$WEBHOOK_TOKEN \
-H 'content-type: application/json' \
-d '{
"enquiryId": "ENQ-20931",
"email": "applicant@example.com",
"programme": "MSc Data Science"
}'
# Inside the workflow: $.input.programme → "MSc Data Science"
Model Context Protocol
Make any system agent-ready with an open standard.
Wrap approved operations from your own systems as an MCP server — or connect one you already run. Gecko discovers the tools, IT grants them one checkbox at a time, and every call appears in run traces.
- Remote servers over Streamable HTTP or SSE, with custom headers, saved integration credentials or per-user OAuth sign-in
- Per-agent, per-tool grants — nothing is granted by default
- Test bench — inspect each tool’s schema, fill a generated form and run a live call before any agent can
- Portable — a server you build for Gecko works with any MCP client
Tool
Response · 212 ms
rooms.checkAvailabilityroomId · string
LT-204
date · date
2026-10-14
{ "available": true, "nextBooking": "14:00" }
Custom Code
When a step needs logic of its own.
Write Node.js inside a workflow — or describe what you need and let the AI code assistant draft it — then test it against a sample payload before saving.
Isolated sandbox
Each execution runs in its own isolated sandbox — never on the platform — with a choice of Node.js runtimes and a hard 300-second limit.
Secrets at run time
Bind encrypted secrets to environment variables. They are resolved only at execution, and leaked values are replaced with [REDACTED] in errors.
AI code assistant
Describe the transformation or API call and the assistant writes the step’s JavaScript, using any chat model your tenant has enabled.
Portability
Your logic is yours. Take it with you.
Institutional AI shouldn’t be a one-way door. Every investment you make on Gecko is built to outlive any single vendor — including us.
- Workflows export and import as JSON in a versioned
gecko.workflowformat — through the console or the API - Models are a setting — swap the provider behind a live agent without rebuilding it
- Tools use MCP — the open standard, portable to any MCP client
- Prompts in a central library with version history you can diff and restore
// GET /api/v1/workflows/{id}/export
{
"format": "gecko.workflow",
"schemaVersion": 1,
"workflow": {
"name": "Support triage",
"graph": {
"nodes": [
{ "id": "workflow-entry", "data": { "type": "entry", … } },
{ "id": "classify", "data": { "type": "generateText", … } }
],
"edges": [ … ]
}
}
}
Web embed
One script tag. No token in the browser.
Add a floating chat, inline chat or AI search experience to any approved site. The runtime is dependency-free, isolated in Shadow DOM and never exposes a tenant API token to the page.
- Three modes —
bubble,inlineandsearch— with an optional target container - Origin allow-lists per widget, including wildcard subdomains
- Safe rendering — Markdown built without
innerHTML, restricted link protocols, model-supplied images never fetched
<!-- AI search, inserted where the tag sits -->
<script
src="https://…/embed/gecko-embed.js"
data-gecko-widget="WIDGET_ID"
data-mode="search"
data-api-base="https://…/api/v1"
defer
></script>
Architecture
A modern stack, deployed per region.
For the architects in the room: what’s under the hood, and how it scales.
TypeScript service
A Bun and TypeScript API with request validation on every route and a generated OpenAPI contract.
PostgreSQL + pgvector
Relational data and embeddings together, with full-text search fused with vector similarity for hybrid retrieval.
Autoscaling workers
Crawling, embedding, knowledge sync and workflow execution run as workers on AWS ECS, scaled on queue depth.
Regional stacks
Independent deployments in Ireland, the US and Canada, each with its own database, Redis, secrets and domain.
Keep exploring
Architecture review
Bring your architects. We’ll bring ours.
Walk through the API, identity, data flows and integration patterns with the engineers who build the platform.
- API and SDK walkthrough
- Integration and MCP patterns for your estate
- Assurance documents in our Trust Center