> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/using-the-api/openapi-specs.md). # OpenAPI specs The [API reference](/api/api-reference.md) is generated from OpenAPI 3.2 specifications. The same specifications are published to npm as [`@celigo/api-specs`](https://www.npmjs.com/package/@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](#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](#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](#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](https://developer.celigo.com/mcp) `get_schema` tool and the CLI's [AI assistant skills](https://developer.celigo.com/cli/using-the-cli/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](https://developer.celigo.com/cli) is a complete client for the same API, and every reference page includes a console for trying calls against your own account. ## Install ```bash 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: ```bash npm pack @celigo/api-specs tar -xzf celigo-api-specs-*.tgz ls package/dist ``` ## What's in the package | Path | Contents | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `dist/.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](/api/getting-started/environments.md). * One security scheme, `bearerAuth`, applied to every operation. Send `Authorization: Bearer ` — see [Authentication](/api/getting-started/authentication.md). ## 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](https://developer.celigo.com/api/api-reference/account-and-admin/account) | | `agent.yml` | [On-premise Agents](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/on-premise-agents) | | `ai-agent.yml` | [AI Agents](https://developer.celigo.com/api/api-reference/ai-and-mcp/ai-agents) | | `api.yml` | [APIs](https://developer.celigo.com/api/api-reference/api-management/apis) | | `apim.yml` | [APIM](https://developer.celigo.com/api/api-reference/api-management/apim) | | `asynchelper.yml` | [Async Helpers](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/async-helpers) | | `audit.yml` | [Audit Logs](https://developer.celigo.com/api/api-reference/monitoring/audit-logs) | | `connection.yml` | [Connections](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/connections) | | `connector.yml` | [Connectors](https://developer.celigo.com/api/api-reference/marketplace-and-templates/connectors) | | `ediprofile.yml` | [EDI Profiles](https://developer.celigo.com/api/api-reference/b2b-manager/edi-profiles) | | `editransaction.yml` | [EDI Transactions](https://developer.celigo.com/api/api-reference/b2b-manager/edi-transactions) | | `enduser.yml` | [End Users](https://developer.celigo.com/api/api-reference/account-and-admin/end-users), [Groups](https://developer.celigo.com/api/api-reference/account-and-admin/groups), [Roles](https://developer.celigo.com/api/api-reference/account-and-admin/roles) | | `environment.yml` | [Environments](https://developer.celigo.com/api/api-reference/account-and-admin/environments) | | `eventreport.yml` | [Event Reports](https://developer.celigo.com/api/api-reference/monitoring/event-reports) | | `export.yml` | [Exports](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/exports) | | `filedefinition.yml` | [File Definitions](https://developer.celigo.com/api/api-reference/b2b-manager/file-definitions) | | `filestorage.yml` | [File Storage](https://developer.celigo.com/api/api-reference/data-stores/file-storage) | | `flow.yml` | [Flows](https://developer.celigo.com/api/api-reference/integrations-and-flows/flows) | | `guardrail.yml` | [Guardrails](https://developer.celigo.com/api/api-reference/ai-and-mcp/guardrails) | | `httpconnector.yml` | [HTTP Connectors](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/http-connectors) | | `httpconnectorendpoint.yml` | [HTTP Connector Endpoints](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/http-connector-endpoints) | | `httpconnectorresource.yml` | [HTTP Connector Resources](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/http-connector-resources) | | `iclient.yml` | [iClients](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/iclients) | | `import.yml` | [Imports](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/imports) | | `integration.yml` | [Integrations](https://developer.celigo.com/api/api-reference/integrations-and-flows/integrations) | | `job.yml` | [Jobs](https://developer.celigo.com/api/api-reference/monitoring/jobs) | | `lookupcache.yml` | [Lookup Caches](https://developer.celigo.com/api/api-reference/data-stores/lookup-caches) | | `marketplace.yml` | [Marketplace](https://developer.celigo.com/api/api-reference/marketplace-and-templates/marketplace) | | `mcp-oauth-provider.yml` | [MCP OAuth Providers](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-oauth-providers) | | `mcp-server.yml` | [MCP Servers](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers) | | `notification.yml` | [Notifications](https://developer.celigo.com/api/api-reference/monitoring/notifications) | | `processor.yml` | [Parsers & Generators](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators) | | `profile.yml` | [Profile](https://developer.celigo.com/api/api-reference/account-and-admin/profile) | | `recyclebin.yml` | [Recycle Bin](https://developer.celigo.com/api/api-reference/account-and-admin/recycle-bin) | | `script.yml` | [Scripts](https://developer.celigo.com/api/api-reference/scripts-and-stacks/scripts) | | `stack.yml` | [Stacks](https://developer.celigo.com/api/api-reference/scripts-and-stacks/stacks) | | `state.yml` | [State](https://developer.celigo.com/api/api-reference/data-stores/state) | | `subscription.yml` | [Subscription & Entitlements](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements) | | `sync.yml` | [Syncs](https://developer.celigo.com/api/api-reference/data-ingestion/syncs), [Sync Jobs](https://developer.celigo.com/api/api-reference/data-ingestion/sync-jobs) | | `tag.yml` | [Tags](https://developer.celigo.com/api/api-reference/monitoring/tags) | | `template.yml` | [Templates](https://developer.celigo.com/api/api-reference/marketplace-and-templates/templates) | | `tool.yml` | [Tools](https://developer.celigo.com/api/api-reference/exports-imports-and-tools/tools) | | `tradingpartnerconnector.yml` | [Trading Partner Connectors](https://developer.celigo.com/api/api-reference/b2b-manager/trading-partner-connectors) | | `user.yml` | [Users](https://developer.celigo.com/api/api-reference/account-and-admin/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`](https://www.npmjs.com/package/openapi-typescript) to turn the Tags spec into TypeScript types: ```bash 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`: ```typescript Tag: WithRequired & { /** * @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](https://www.npmjs.com/package/@stoplight/prism-cli) serves a spec as a local mock server that validates requests and answers from the spec's examples. Start one for the Tags spec: ```bash 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. ```bash curl -s http://127.0.0.1:4010/v1/tags -H "Authorization: Bearer $CELIGO_API_TOKEN" ``` ```json [{"_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. ```bash 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. ```bash mkdir old new (cd old && npm pack @celigo/api-specs@ && 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](https://docs.celigo.com/hc/en-us/requests/new). Include the package version, the file name, and the request that exposed the difference. Never include tokens or customer data. ## Related links * [API reference](/api/api-reference.md) — browse every endpoint and try calls against your account. * [Authentication](/api/getting-started/authentication.md) — create the token a generated client sends as `bearerAuth`. * [Environments & regions](/api/getting-started/environments.md) — which `servers` entry to select. * [Celigo CLI](https://developer.celigo.com/cli) — drive the same API from the terminal without generating a client.