# 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:

```http
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` replaces the entire resource body. Any field you **omit** will be unset on the server. 

To rename a connection without breaking it you must:

1. Fetch the full current body.

**Request:**

```http
GET /v1/connections/5f83a9b2c7d3e8f1a2b3c4d5 HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Accept: application/json
```

**Response:**

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

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

**Modified `name`:**

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

3. Execute `PUT /v1/connections/{id}` with the **complete** modified body**:**

```json
{
  "_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.&#x20;
2. Query params are camelCase.&#x20;
3. `Type` discriminators, like `adaptorType`, are PascalCase and case-sensitive:

```json
{ "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:

```json
"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 gotcha above.
* Arrays default to `[]`, not `null`. An empty array means "zero elements," not "unset."

## Search-style query params

Many list endpoints accept `search` or `q` along with per-resource filters. See [Sorting & filtering](/api/using-the-api/sorting-filtering.md).

## Idempotency

* `GET` is always safe to retry.
* `DELETE` is idempotent: the second call returns `404` 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.celigo.com/api/getting-started/api-conventions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.