@celigo/api-specs
OpenAPI 3.2 specifications for the Celigo integrator.io REST API, packaged as files for tooling. They are the documents behind the API reference on the Celigo Developer Platform, and what the Celigo CLI validates resource documents against.
npm install @celigo/api-specs
What's in the package
Every platform resource has its own OpenAPI document under dist/ — connections, flows, exports,
imports, integrations, jobs, scripts, tools, and the rest. Each file is self-contained, with every
$ref already inlined, so it can go straight into a client generator, a request validator, or an
AI agent's context with no loader configuration.
dist/connection.yml
dist/flow.yml
dist/export.yml
dist/import.yml
...
schemas.json
schemas.json is the schema pack that the Celigo CLI's celigo lint command validates documents
against, compiled from the same bundles. Other consumers can ignore it.
Resolve a document the same way as any other packaged file:
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const specPath = require.resolve("@celigo/api-specs/dist/connection.yml");
The API these specs describe
All operations live under the /v1/ prefix and authenticate with a bearer token
(Authorization: Bearer <token>). Create a token in integrator.io under Resources >
API tokens.
The API is served from four regional hosts. Use the one your account lives in:
| Region | Base URL |
|---|---|
| US (default) | https://api.integrator.io |
| EU | https://api.eu.integrator.io |
| AU | https://api.au.integrator.io |
| CA | https://api.ca.integrator.io |
API Management (/v1/apim/...) is served from the US and EU hosts only.
To browse the API interactively, use the rendered reference: each resource has its own page, with a console for trying calls against your own account.
What the specs cover
The specs are prescriptive. They describe the API surface Celigo supports and intends to keep supporting — not everything the server happens to tolerate. Internal endpoints, deprecated fields, and retired enum values are deliberately left out.
The practical consequence: a request that validates against these specs is one you can build on. The reverse does not hold. The server may accept a payload no spec describes, and that payload may be ignored or rejected later.
Extensions
Alongside standard OpenAPI, the documents carry x- extensions that Celigo tooling reads. Standard
OpenAPI consumers can ignore them; validators and AI agents may find them useful.
| Extension | Where | Meaning |
|---|---|---|
x-enumDescriptions | Fields with enum | One line per enum value explaining what it does. |
x-celigo-refModel | ID fields | The resource type the ID points at (flows, scripts, and so on). |
x-celigo-ai-guidance | Schemas and fields | Operational hints for AI agents: which default to choose, what to set when scaffolding, and the concrete failure that results from getting it wrong. |
x-celigo-ui-override | Schemas and fields | Marks a requirement or default that mirrors the integrator.io form, which is stricter than the raw API, so generated configurations are complete and connectable. |
x-celigo-agent | Expression fields | The field's value is authored in an expression language or editor; its capability tags (handlebars, sql, mapping, …) tell an agent or tool which one. |
x-celigo-handlebars-context | Handlebars fields | The data context the expression is evaluated against, such as pre-mapped or post-mapped. |
x-celigo-excludeAdaptorTypes | Shared adaptor fields | Adaptor types the field does not apply to. |
x-lowercase, x-uppercase | String fields | The API normalizes the value's case on save. |
x-internal, x-enable-proxy, and x-displayName control the documentation toolchain and carry no
API meaning.
Support
For a problem with the specs — a schema that disagrees with the API, a missing field or endpoint, a description that led you somewhere wrong — or with integrator.io itself, contact Celigo Support. The most useful report names the spec and operation, shows the request you made, and shows what the API returned next to what the spec said it would. Never include API tokens, credentials, or customer data.
Report a suspected security vulnerability through the same channel, privately, with the spec and operation involved, what it discloses or enables, and reproduction steps.
License
MIT. The LICENSE file ships in the package. The specs describe the integrator.io API; use of the
API itself is governed by your Celigo agreement.