API conventions

Patterns that are true across every endpoint in the Celigo REST API. Learn these once and you can read any page in the reference.

JSON language

Requests and responses are JSON. Set:

Accept: application/json
Content-Type: application/json

Non-JSON bodies return 415 Unsupported Media Type. Binary uploads (file definitions, connector artifacts) use multipart/form-data on the specific endpoints that accept them — always documented on the endpoint page.

Resource IDs

Every resource has a 24-character hexadecimal _id:

5f83a9b2c7d3e8f1a2b3c4d5

IDs are opaque. Do not parse them, sort them, or compare them as integers. The _id is stable for the lifetime of the resource and is what you use in all path parameters (/v1/integrations/{id}).

Some resources also expose a human-readable name. Names are not unique; always reference resources by _id in any automation.

Standard fields

Every resource carries these on read:

Field	Type	Description
_id	string	Stable resource identifier.
name	string	Human name. Not unique.
createdAt	ISO date	When the resource was created.
lastModified	ISO date	When the resource was last written.
lastModifiedBy	string	_id of the user that last wrote it.

On POST you omit these; the server sets them.

HTTP methods

Verb	Semantic
GET	Read. Never has side effects.
POST	Create a new resource, or invoke a verb-style action (e.g., POST /.../test).
PUT	Full replace of the resource body. Destructive; see below.
PATCH	Merge update. Only supported on a subset of endpoints.
DELETE	Delete.

PUT is destructive

⚠️ PUT is destructive — it replaces the entire resource body. Any field you omit is unset on the server. GET the current body, modify only the fields you want to change, then PUT the complete object back.

To rename a connection without breaking it you must:

1. Fetch the full current body.

Request:

GET /v1/connections/5f83a9b2c7d3e8f1a2b3c4d5 HTTP/1.1
Authorization: Bearer <YOUR_API_TOKEN>
Accept: application/json

Response:

{
  "_id":  "5f83a9b2c7d3e8f1a2b3c4d5",
  "name": "httpbin source",
  "type": "http",
  "http": { "baseURI": "https://httpbin.org", "auth": { "type": "basic" } },
  "_iClientId": "6a1b2c3d4e5f6a7b8c9d0e1f"
}

1. Modify the field(s) you want to change (name in this case).

Modified name:

{
  "_id":  "5f83a9b2c7d3e8f1a2b3c4d5",
  "name": "httpbin source (modified)",
  "type": "http",
  "http": { "baseURI": "https://httpbin.org", "auth": { "type": "basic" } },
  "_iClientId": "6a1b2c3d4e5f6a7b8c9d0e1f"
}

1. Execute PUT /v1/connections/{id} with the complete modified body:

{
  "_id":  "5f83a9b2c7d3e8f1a2b3c4d5",
  "name": "httpbin source (modified)",
  "type": "http",
  "http": { "baseURI": "https://httpbin.org", "auth": { "type": "basic" } },
  "_iClientId": "6a1b2c3d4e5f6a7b8c9d0e1f"
}

Let the CLI do it. celigo connections set <id> name="renamed" performs the full GET-modify-PUT cycle for you. Skip the hand-rolled version unless you're working in a language without a Celigo SDK.

Case sensitivity

Case sensitivity is as follows:

1. Paths are lowercase.
2. Query params are camelCase.
3. Type discriminators, like adaptorType, are PascalCase and case-sensitive:

{ "adaptorType": "NetSuiteDistributedImport" }  // valid
{ "adaptorType": "netsuitedistributedimport" }  // 422

The same rules apply to type, _connectionType, and most other union discriminators.

Timestamps

Dates use ISO 8601 with a Z suffix, always UTC:

"createdAt": "2026-04-21T18:52:06.208Z"

Avoid local-time strings on writes. Convert explicitly if your inputs are in another timezone.

Nullability

• Optional scalar fields omitted on the response mean "not set."
• Writing null to a field clears it. Writing undefined (omitting the key) on a PUT also clears it — that's the destructive-PUT behavior above.
• Arrays default to [], not null. An empty array means "zero elements," not "unset."

Filtering query params

There's no universal search/q parameter. Filtering is per-endpoint — each list endpoint documents the exact query parameters it accepts, and unrecognized parameters are silently ignored. See Sort & filter.

Idempotency

• GET is always safe to retry.
• DELETE is idempotent: the second call returns 404 Not Found but the state is the same.
• POST is not idempotent. A client retry after a network error may create a duplicate. If that's a concern, GET by a known unique field (like name + _integrationId) before the POST and skip if it already exists, or use PUT with a client-chosen _id on endpoints that support it.