OpenAPI specs

The API reference is generated from OpenAPI 3.2 specifications. The same specifications are published to npm as @celigo/api-specs, one self-contained document per resource. Install the package when your own code or tooling needs the specs as files.

When to use the package

The reference pages are the specs rendered for people. The package is the same specs for machines. Install it when you are building something against the API and the tool you are using needs the spec as an input.

You want to	The spec gives you	Tooling
Generate a typed client or types	Every resource shape, discriminator, and read-only flag as code. A wrong field name fails at compile time instead of with 422 Unprocessable Entity.	openapi-typescript, OpenAPI Generator, Kiota — see Generate types from a spec
Validate resource JSON in CI	A schema for the flow, export, and import documents you keep in Git. Catch a malformed body before a PUT replaces the live resource with it.	Any OpenAPI-aware request validator
Mock the API in tests	A local server that answers with schema-valid responses, so tests run without a token, a live account, or rate limits.	Prism — see Mock the API
See exactly what changed	Pin a version, and diff the two dist/ trees when you upgrade: new fields, enum values, and constraints, per resource.	diff — see Versioning
Import into API tools	A ready-made collection per resource in Postman, Insomnia, or Bruno, or a definition for an API gateway.	Any tool with OpenAPI import
Ground an AI agent	Structured schemas an agent can load and slice by path or component, plus x-celigo-ai-guidance prose written for that purpose. The Platform MCP get_schema tool and the CLI's AI assistant skills draw from these same specs.	Your agent framework

You do not need the package to call the API from a shell or a script. The Celigo CLI is a complete client for the same API, and every reference page includes a console for trying calls against your own account.

Install

npm install --save-exact @celigo/api-specs

The package contains no JavaScript and has no runtime dependencies. The documents are in node_modules/@celigo/api-specs/dist/.

To download the files without adding a dependency to a project:

npm pack @celigo/api-specs
tar -xzf celigo-api-specs-*.tgz
ls package/dist

What's in the package

Path	Contents
dist/<resource>.yml	44 OpenAPI 3.2.0 documents, one per resource. Every $ref resolves inside the same file, so each document is valid on its own with no loader configuration.
schemas.json	A compiled schema pack for the Celigo CLI. Use the dist/ documents for your own tooling.
README.md, LICENSE	Package notes and the MIT license.

Every document declares the same top-level contract:

• openapi: 3.2.0. Confirm your generator or validator supports OpenAPI 3.2 before you start. Tools that parse only 3.0 or 3.1 may reject the document.

• Four servers entries: https://api.integrator.io (US, listed first), https://api.eu.integrator.io, https://api.au.integrator.io, and https://api.ca.integrator.io. Most generators default to the first server. Select the one for your region — see Environments & regions.

• One security scheme, bearerAuth, applied to every operation. Send Authorization: Bearer <YOUR_API_TOKEN> — see Authentication.

Files and reference pages

File names follow the API path, not the page title. Use this table to move between a dist/ file and its rendered reference page.

File	Reference page
account.yml	Account
agent.yml	On-premise Agents
ai-agent.yml	AI Agents
api.yml	APIs
apim.yml	APIM
asynchelper.yml	Async Helpers
audit.yml	Audit Logs
connection.yml	Connections
connector.yml	Connectors
ediprofile.yml	EDI Profiles
editransaction.yml	EDI Transactions
enduser.yml	End Users, Groups, Roles
environment.yml	Environments
eventreport.yml	Event Reports
export.yml	Exports
filedefinition.yml	File Definitions
filestorage.yml	File Storage
flow.yml	Flows
guardrail.yml	Guardrails
httpconnector.yml	HTTP Connectors
httpconnectorendpoint.yml	HTTP Connector Endpoints
httpconnectorresource.yml	HTTP Connector Resources
iclient.yml	iClients
import.yml	Imports
integration.yml	Integrations
job.yml	Jobs
lookupcache.yml	Lookup Caches
marketplace.yml	Marketplace
mcp-oauth-provider.yml	MCP OAuth Providers
mcp-server.yml	MCP Servers
notification.yml	Notifications
processor.yml	Parsers & Generators
profile.yml	Profile
recyclebin.yml	Recycle Bin
script.yml	Scripts
stack.yml	Stacks
state.yml	State
subscription.yml	Subscription & Entitlements
sync.yml	Syncs, Sync Jobs
tag.yml	Tags
template.yml	Templates
tool.yml	Tools
tradingpartnerconnector.yml	Trading Partner Connectors
user.yml	Users

What the specs describe

The specs are prescriptive. They describe the API surface Celigo supports and intends to keep supporting, not everything the server accepts. Internal operations, deprecated fields, and retired enum values are removed before publishing.

A request that validates against a spec is one you can build on. The reverse does not hold. The live server is often more permissive than the spec, and a field it accepts today may be ignored or rejected later if no spec describes it.

Celigo extensions

The documents carry x- extension fields that Celigo tooling reads. Standard OpenAPI consumers can ignore all of them. Three are useful if you build your own tooling on the specs:

Extension	Where it appears	What it holds
x-enumDescriptions	Next to an enum	What each value does, keyed by value.
x-celigo-refModel	On an _id string field	The resource type the ID points at, such as flows or integrations.
x-celigo-ai-guidance	On info, operations, and schemas	Prose guidance for AI agents that build requests from the spec.

The remaining x- fields, such as x-celigo-ui-override, configure Celigo's own builders. x-internal is always false in published documents.

Generate types from a spec

Each document is a standard OpenAPI file, so any generator that reads OpenAPI 3.2 can consume it directly. This example uses openapi-typescript to turn the Tags spec into TypeScript types:

npx openapi-typescript@7 node_modules/@celigo/api-specs/dist/tag.yml -o tag.d.ts

The generated Tag type carries the field descriptions over as JSDoc and marks server-owned fields readonly:

Tag: WithRequired<components["schemas"]["ResourceResponse"], "_id"> & {
    /**
     * @description Human-readable tag name. Appears on read-side error records.
     * @example Urgent
     */
    tag: string;
    /**
     * @description Short code used when writing tag references — e.g. as the values
     *     in `PUT /v1/flows/{_id}/{_stepId}/tags` `tagIds[]`.
     *     Server-generated and immutable: `tagId` values supplied on
     *     create/update are ignored and a fresh code is generated.
     * @example rx618
     */
    readonly tagId: string;
};

Run the same command against flow.yml, export.yml, or import.yml for the large resources. Each spec generates independently, so generate only the resources your code touches.

Mock the API

Prism serves a spec as a local mock server that validates requests and answers from the spec's examples. Start one for the Tags spec:

npx @stoplight/prism-cli@5 mock node_modules/@celigo/api-specs/dist/tag.yml

Then call it as you would the real API. The mock enforces the bearerAuth scheme, so the header is required; any value passes.

curl -s http://127.0.0.1:4010/v1/tags -H "Authorization: Bearer $CELIGO_API_TOKEN"

[{"_id":"6555119c0a137977fb1e7994","tag":"Ignore","tagId":"NjMMA"},{"_id":"69a1e79bdbb446adf7933049","tag":"IT Related Login Issue","tagId":"P3mzf"}]

Versioning

The package version tracks the specifications, not the API. The API stays at /v1/; the package moves whenever a spec changes, which can be several times a week. Pin an exact version so a spec update cannot change generated code without review, then upgrade on your own schedule.

npm view @celigo/api-specs version    # latest published version
npm install --save-exact @celigo/api-specs@latest

To see what an upgrade changes before you take it, unpack both versions and diff the dist/ trees. The files are YAML, so a plain diff reads well; an OpenAPI-aware diff tool adds breaking-change classification.

mkdir old new
(cd old && npm pack @celigo/api-specs@<CURRENT_VERSION> && tar -xzf *.tgz)
(cd new && npm pack @celigo/api-specs@latest && tar -xzf *.tgz)
diff -rq old/package/dist new/package/dist          # which resources changed
diff -u old/package/dist/job.yml new/package/dist/job.yml   # what changed in one

Report a problem

If a schema disagrees with the API, a field or endpoint is missing, or a description is inaccurate, open a ticket with Celigo Support. Include the package version, the file name, and the request that exposed the difference. Never include tokens or customer data.

Related links

• API reference — browse every endpoint and try calls against your account.

• Authentication — create the token a generated client sends as bearerAuth.

• Environments & regions — which servers entry to select.

• Celigo CLI — drive the same API from the terminal without generating a client.