For the complete documentation index, see llms.txt. This page is also available as Markdown.

File Storage

Celigo Storage is managed file storage built into integrator.io for staging files between flows and giving integrations persistent files to work with. Organize content into files and folders, transfer bytes directly through short-lived presigned S3 URLs, and reference stored files from flows. Items are addressed by _id and placed by parent folder; renames and moves keep the _id stable, and deletes go to a 30-day recycle bin before they can be purged.

Storage item schema

Initiate file upload

post
/v1/storage/files/initiateUpload

Starts one or more file uploads. For each file, reserves quota, creates a pending item, and returns presigned S3 URLs to transfer the bytes to: a single PUT URL for files up to 5 GB, or a multipart uploadId, partUrls, and completeUrl for larger files. Upload the bytes directly to those URLs, then the item flips to active once S3 confirms it — no further API call is needed. URLs expire after one hour; reissue them with POST /v1/storage/files/refresh-urls. Each file is validated independently, so the response can mix per-file successes and failures while the request itself returns 200.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

Reserves quota and requests presigned upload URLs for one or more files.

_parentIdstring · nullableOptional

Folder to create the files in. Omit or pass null to upload to the account root. Must reference an existing active folder.

Example: 683a1f2e9b0c4d001e8f7a23
Responses
200

Per-file upload instructions, in request order.

application/json

Per-file upload instructions, in the same order as the request.

post/v1/storage/files/initiateUpload
POST /v1/storage/files/initiateUpload HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 129

{
  "_parentId": "683a1f2e9b0c4d001e8f7a23",
  "files": [
    {
      "name": "logo.png",
      "mimeType": "image/png",
      "size": 245760,
      "uploadType": "single"
    }
  ]
}
{
  "files": [
    {
      "_id": "683b2a0e1c3d5f001a9e8b01",
      "name": "logo.png",
      "statusCode": 200,
      "body": {
        "uploadType": "single",
        "uploadUrl": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/presigned-put-url"
      }
    },
    {
      "_id": "683b2a0e1c3d5f001a9e8b03",
      "name": "database-export.sql",
      "statusCode": 200,
      "body": {
        "uploadType": "multipart",
        "uploadId": "abcD12efGHIjklMN3opQrst",
        "partUrls": [
          {
            "partNumber": 6,
            "url": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/part-6"
          },
          {
            "partNumber": 7,
            "url": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/part-7"
          }
        ],
        "completeUrl": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/complete"
      }
    },
    {
      "name": "invalid-file",
      "statusCode": 400,
      "errors": [
        {
          "code": "STORAGE_INVALID_MIME_TYPE",
          "message": "Invalid MIME type"
        }
      ]
    }
  ]
}

Refresh upload URLs

post
/v1/storage/files/refresh-urls

Reissues presigned upload URLs for pending uploads whose URLs have expired (URLs last one hour). For a single PUT, returns a fresh upload URL; for multipart, returns fresh URLs for the requested part numbers plus the complete URL. Already-uploaded parts are preserved. Each item is processed independently.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

Reissues presigned URLs for pending uploads whose URLs have expired.

Responses
200

Per-item refreshed upload instructions.

application/json

Per-item refreshed upload instructions.

post/v1/storage/files/refresh-urls
POST /v1/storage/files/refresh-urls HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "items": [
    {
      "_id": "683b2a0e1c3d5f001a9e8b01",
      "uploadType": "single"
    },
    {
      "_id": "683b2a0e1c3d5f001a9e8b03",
      "uploadType": "multipart",
      "uploadId": "abcD12efGHIjklMN3opQrst",
      "partNumbers": [
        3,
        4,
        5
      ]
    }
  ]
}
{
  "items": [
    {
      "_id": "683b2a0e1c3d5f001a9e8b03",
      "name": "database-export.sql",
      "statusCode": 200,
      "body": {
        "uploadType": "multipart",
        "uploadId": "abcD12efGHIjklMN3opQrst",
        "partUrls": [
          {
            "partNumber": 3,
            "url": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/fresh-part-3"
          }
        ],
        "completeUrl": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/fresh-complete"
      }
    }
  ]
}

Cancel a multipart upload

post
/v1/storage/files/{_id}/cancel

Aborts an in-progress multipart upload, discarding any uploaded parts and releasing the reserved quota. Use this to abandon a multipart upload started with POST /v1/storage/files/initiateUpload; single PUT uploads do not need canceling. If the upload has in fact already completed in S3, the item is activated instead and the request is rejected as not pending.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the pending multipart item to cancel.

Example: 683b2a0e1c3d5f001a9e8b03
Responses
204

Multipart upload aborted and the pending item removed.

No content

post/v1/storage/files/{_id}/cancel
POST /v1/storage/files/{_id}/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get a file download URL

get
/v1/storage/files/{_id}/download

Returns a short-lived presigned S3 URL for downloading a file's content, along with how many seconds it stays valid. Fetch the bytes directly from that URL — the content does not pass through this API. Files only; folders have no content to download.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the file to download.

Example: 683b2a0e1c3d5f001a9e8b01
Responses
200

A presigned download URL and its lifetime.

application/json
downloadUrlstring · uriRequired

Presigned S3 URL to GET the file's bytes from.

Example: https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/...
expiresInintegerRequired

Seconds the URL stays valid from the time of this response.

Example: 3600
get/v1/storage/files/{_id}/download
GET /v1/storage/files/{_id}/download HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "downloadUrl": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/...",
  "expiresIn": 3600
}

List or search items

get
/v1/storage/items

Browse or search Celigo Storage. In list mode (no search), returns the direct children of a folder — omit _parentId for the account root — and includes a breadcrumb of the path to that folder. In search mode (with search), recursively matches item names across the whole account and returns each hit's location. Results are paginated with the Link response header.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
_parentIdstring · objectIdOptional

Folder whose direct children to list. Omit for the account root. Ignored in search mode.

Example: 683a1f2e9b0c4d001e8f7a23
searchstring · min: 2Optional

Recursive, case-insensitive substring match on item names across the whole account. Switches the endpoint to search mode, where _parentId is ignored and each item carries its location. Matches names only, not contents or descriptions.

Example: report
typestring · enumOptional

Restrict results to one item type.

Example: filePossible values:
mimeTypestringOptional

Restrict results to files of a single media type.

Example: image/png
sort_bystring · enumOptional

Field to sort by.

Default: nameExample: namePossible values:
sort_orderstring · enumOptional

Sort direction.

Default: ascExample: ascPossible values:
lastModified_gtestring · date-timeOptional

Return only items modified at or after this time.

Example: 2026-03-01T00:00:00.000Z
lastModified_ltestring · date-timeOptional

Return only items modified at or before this time.

Example: 2026-03-31T23:59:59.999Z
pageSizeinteger · min: 1 · max: 1000Optional

Maximum number of items to return per page.

Default: 1000Example: 100
afterstringOptional

Opaque cursor for the next page. Take it from the Link response header's rel="next" URL rather than constructing it. Cannot be combined with before.

Example: eyJsYXN0SWQiOiI2ODNiMmEwZTFjM2Q1ZjAwMWE5ZThiMDEifQ
beforestringOptional

Opaque cursor for the previous page, taken from the Link header's rel="prev" URL. Cannot be combined with after.

Example: eyJmaXJzdElkIjoiNjg0YzNiMWYyZDRlNmcwMDJiMGg5YzM0In0
Responses
200

Matching items. Includes breadcrumb in list mode and per-item location in search mode.

application/json
get/v1/storage/items
GET /v1/storage/items HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "items": [
    {
      "_id": "684c3b1f2d4e6g002b0h9c34",
      "type": "folder",
      "name": "Reports",
      "status": "active",
      "isSystem": false,
      "createdAt": "2026-03-28T10:00:00.000Z",
      "lastModified": "2026-03-28T14:30:00.000Z"
    },
    {
      "_id": "683b2a0e1c3d5f001a9e8b01",
      "type": "file",
      "name": "logo.png",
      "size": 245760,
      "mimeType": "image/png",
      "status": "active",
      "isSystem": false,
      "createdAt": "2026-03-28T09:00:00.000Z",
      "lastModified": "2026-03-28T09:00:00.000Z"
    }
  ],
  "breadcrumb": [
    {
      "_id": "683a1f2e9b0c4d001e8f7a23",
      "name": "My Files"
    }
  ]
}

Create a folder

post
/v1/storage/items

Creates an empty folder. Folders are organizational only — they hold no content and do not count against storage quota. To create files, use POST /v1/storage/files/initiateUpload.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

Request body for creating a folder.

namestring · max: 256Required

Folder name. Duplicate names within the same parent are allowed.

Example: Reports
_parentIdstring · nullableOptional

Parent folder to create this folder in. Omit or pass null to create it at the account root. Must reference an existing active folder.

Example: 683a1f2e9b0c4d001e8f7a23
descriptionstring · max: 1000Optional

Optional note describing the folder.

Example: Quarterly financial reports
Responses
201

Created folder.

application/json

A file or folder stored in Celigo Storage.

_idstring · objectIdRead-onlyRequired

Unique identifier for the item. Pass it to download, move, copy, replace, rename, or delete the item; folders and files share one ID space.

Example: 683b2a0e1c3d5f001a9e8b01
typestring · enumRead-onlyRequired

Distinguishes a content-bearing file from an organizational folder. Fixed when the item is created and never changes.

Possible values:
namestring · max: 256Required

Display name, including the extension for files (for example orders.csv). Two items with the same name can coexist in one folder — the name is not a unique key.

Example: logo.png
_parentIdstring · nullableRead-onlyOptional

Folder that contains this item. Null when the item sits at the account root.

Example: 683a1f2e9b0c4d001e8f7a23
__ancestorIdsstring · objectId[]Read-onlyOptional

Folder IDs from the root down to the immediate parent, in order. Empty for root-level items. Rewritten automatically when the item or any ancestor folder is moved.

Example: ["683a1f2e9b0c4d001e8f7a23"]
sizeinteger · int64Read-onlyOptional

File size in bytes. Present when type is file; folders carry no size. While an upload is pending this reflects the reserved quota, and is reconciled to the actual byte count once the upload finalizes.

Example: 245760
mimeTypestring · max: 256Read-onlyOptional

Media type recorded at upload time, used to set the download Content-Type. Present when type is file; absent for folders and for files uploaded without a declared type.

Example: image/png
descriptionstring · max: 1000Optional

Optional caller-supplied note describing the item.

Example: Quarterly financial reports
statusstring · enumRead-onlyRequired

Upload lifecycle state. A file is created pending at initiate-upload and flips to active once S3 confirms the bytes; folders are created active.

Possible values:
isSystembooleanRead-onlyRequired

When true, the platform created the item (for example a system or integration folder) and protects it — move, content replace, copy, delete, and purge are rejected with STORAGE_SYSTEM_ITEM_PROTECTED.

deletedAtstring · date-timeRead-onlyOptional

Timestamp when the item was soft-deleted to the recycle bin. Present only for recycle-bin items; the item is permanently purged 30 days after this time unless restored.

Example: 2026-04-27T10:00:00.000Z
deletedBystringRead-onlyOptional

Who soft-deleted the item — a user ID for a direct delete, or cascadeDelete for a descendant removed when its parent folder was deleted. Present only for recycle-bin items. Cascade-deleted items can be recovered only by restoring the folder that was deleted directly.

Example: 60a1b2c3d4e5f6001a2b3c4d
createdAtstring · date-timeRead-onlyRequired

Timestamp when the item was created.

Example: 2026-03-28T09:00:00.000Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp of the most recent metadata change. Updated on rename, move, and content replace, and when the folder's direct children change.

Example: 2026-03-28T14:30:00.000Z
post/v1/storage/items
POST /v1/storage/items HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "name": "Reports"
}
{
  "_id": "684c3b1f2d4e6g002b0h9c34",
  "type": "folder",
  "name": "Reports",
  "description": "Quarterly financial reports",
  "status": "active",
  "isSystem": false,
  "createdAt": "2026-03-30T10:30:00.000Z",
  "lastModified": "2026-03-30T10:30:00.000Z"
}

Look up items in batch

post
/v1/storage/items/batch

Returns metadata for up to 100 items in one call. Send the item ids and optionally a fields projection; by default each result carries only _id. Requesting path adds a breadcrumb path built from the item's ancestor folder names.

With failFast: true (the default), the first unknown id fails the whole request with 422 STORAGE_BATCH_ITEM_NOT_FOUND. With failFast: false, unknown ids come back inline as {_id, notFound: true, reason: "STORAGE_BATCH_ITEM_NOT_FOUND"} entries alongside the found items.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
idsstring · objectId[] · min: 1 · max: 100Required

Item ids to look up. Each must be a 24-character ObjectId; a malformed id fails the request with 400 STORAGE_BATCH_INVALID_REQUEST before any lookup runs.

Example: ["683b2a0e1c3d5f001a9e8b01","684c3b1f2d4e6a002b0f9c34"]
failFastbooleanOptional

When true (the default), an unknown id fails the whole request with 422. When false, unknown ids are reported inline per item and the request still returns 200.

Default: true
Responses
200

Per-id results, in the same order as the requested ids.

application/json
post/v1/storage/items/batch
POST /v1/storage/items/batch HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "ids": [
    "683b2a0e1c3d5f001a9e8b01",
    "684c3b1f2d4e6a002b0f9c34"
  ],
  "fields": [
    "name",
    "size",
    "path"
  ],
  "failFast": false
}
{
  "items": [
    {
      "_id": "683b2a0e1c3d5f001a9e8b01",
      "name": "inv-001.pdf",
      "size": 18244,
      "path": "/invoices/2026/inv-001.pdf"
    },
    {
      "_id": "684c3b1f2d4e6a002b0f9c34",
      "notFound": true,
      "reason": "STORAGE_BATCH_ITEM_NOT_FOUND"
    }
  ]
}

Move items in bulk

post
/v1/storage/items/move

Moves up to 100 files or folders into one destination folder (or the account root) in a single call. Metadata only — content stays in place, ids are unchanged, and quota is unaffected. Folders re-parent immediately and re-anchor their descendants asynchronously.

The destination is validated once up front — a bad destination rejects the whole batch. Each source id is then processed best-effort: the response is 200 when every item moved, or 207 when results are mixed, with a per-id status of success or error. An optional name renames the item as it lands (single-id requests only) so a destination name collision can be resolved without a second call.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
_parentFolderIdstring · nullableRequired

Destination folder. Send null to move the items to the account root. The key must be present — omitting it fails with 400 STORAGE_BULK_MOVE_PARENT_REQUIRED. Must not appear in _storageItemIds (422 STORAGE_BULK_MOVE_DESTINATION_IN_SOURCES).

Example: 684c3b1f2d4e6a002b0f9c34
_storageItemIdsstring · objectId[] · min: 1 · max: 100Required

Ids of the items to move. Over 100 entries fails with 422 STORAGE_BULK_MOVE_TOO_MANY_ITEMS.

Example: ["683b2a0e1c3d5f001a9e8b01"]
namestringOptional

New name applied to the moved item in the same write as the re-parent. Only allowed when _storageItemIds has exactly one entry — with more, the request fails with 400 STORAGE_BULK_MOVE_NAME_DISALLOWED.

Responses
200

Every item moved successfully.

application/json

Per-id move results, one entry per source id.

post/v1/storage/items/move
POST /v1/storage/items/move HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "_parentFolderId": "684c3b1f2d4e6a002b0f9c34",
  "_storageItemIds": [
    "683b2a0e1c3d5f001a9e8b01",
    "683b2a0e1c3d5f001a9e8b02"
  ]
}
{
  "results": [
    {
      "_id": "683b2a0e1c3d5f001a9e8b01",
      "status": "success",
      "_parentId": "684c3b1f2d4e6a002b0f9c34",
      "__ancestorIds": [
        "684c3b1f2d4e6a002b0f9c34"
      ],
      "type": "file"
    }
  ]
}

List recycle-bin items

get
/v1/storage/items/recycleBinTTL

Lists the items currently in the recycle bin, newest deletion first. Only items deleted directly are listed — descendants removed as part of a folder deletion are hidden, since they are restored or purged with their parent. Each item carries deletedAt and deletedBy. Restore an item with POST /v1/storage/items/{_id}/restore or remove it for good with DELETE /v1/storage/items/{_id}/purge.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
pageSizeinteger · min: 1 · max: 1000Optional

Maximum number of items to return per page.

Default: 1000Example: 100
afterstringOptional

Opaque forward-paging cursor. Take it from the previous response's Link header (rel="next"); omit for the first page. Cannot be combined with before.

Example: WyIyMDI2LTA4LTA5VDA0OjQ2OjUwLjI0NloiLCI2YTc3ZmQ0YTAxYjgxODdjMmYzNGEzOGEiLCJkZWxldGVkQXQiLCJkZXNjIl0
beforestringOptional

Opaque backward-paging cursor from a previous response's Link header. Cannot be combined with after.

Responses
200

Recycle-bin items. Pagination is cursor-based via the Link header — the body carries only items.

application/json
get/v1/storage/items/recycleBinTTL
GET /v1/storage/items/recycleBinTTL HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "items": [
    {
      "_id": "683b2a0e1c3d5f001a9e8b01",
      "type": "file",
      "name": "old-report.pdf",
      "size": 245760,
      "mimeType": "application/pdf",
      "status": "active",
      "isSystem": false,
      "deletedBy": "60a1b2c3d4e5f6001a2b3c4d",
      "deletedAt": "2026-04-27T10:00:00.000Z",
      "createdAt": "2026-03-01T09:00:00.000Z",
      "lastModified": "2026-03-28T10:00:00.000Z"
    },
    {
      "_id": "684c3b1f2d4e6g002b0h9c34",
      "type": "folder",
      "name": "Archived Reports",
      "status": "active",
      "isSystem": false,
      "deletedBy": "60a1b2c3d4e5f6001a2b3c4d",
      "deletedAt": "2026-04-25T14:30:00.000Z",
      "createdAt": "2026-02-15T08:00:00.000Z",
      "lastModified": "2026-03-26T14:30:00.000Z"
    }
  ]
}

Rename or describe an item

put
/v1/storage/items/{_id}

Updates an item's name and/or description. Renaming keeps the item's _id stable, so references from flows, exports, imports, and tokens survive. To move an item to a different folder, use PATCH /v1/storage/items/{_id}/move; to replace a file's content, use PATCH /v1/storage/items/{_id}/replace.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

Item ID.

Example: 683b2a0e1c3d5f001a9e8b01
Body

Request body for renaming an item or changing its description. Provide name, description, or both. Folder placement is changed with the move endpoint, not here — _parentId and __ancestorIds are rejected.

namestring · max: 256Optional

New display name for the item.

Example: quarterly-report-final.pdf
descriptionstring · max: 1000Optional

New description. Pass an empty string to clear it.

Example: Updated Q1 2026 financial report
Responses
200

Updated item.

application/json

A file or folder stored in Celigo Storage.

_idstring · objectIdRead-onlyRequired

Unique identifier for the item. Pass it to download, move, copy, replace, rename, or delete the item; folders and files share one ID space.

Example: 683b2a0e1c3d5f001a9e8b01
typestring · enumRead-onlyRequired

Distinguishes a content-bearing file from an organizational folder. Fixed when the item is created and never changes.

Possible values:
namestring · max: 256Required

Display name, including the extension for files (for example orders.csv). Two items with the same name can coexist in one folder — the name is not a unique key.

Example: logo.png
_parentIdstring · nullableRead-onlyOptional

Folder that contains this item. Null when the item sits at the account root.

Example: 683a1f2e9b0c4d001e8f7a23
__ancestorIdsstring · objectId[]Read-onlyOptional

Folder IDs from the root down to the immediate parent, in order. Empty for root-level items. Rewritten automatically when the item or any ancestor folder is moved.

Example: ["683a1f2e9b0c4d001e8f7a23"]
sizeinteger · int64Read-onlyOptional

File size in bytes. Present when type is file; folders carry no size. While an upload is pending this reflects the reserved quota, and is reconciled to the actual byte count once the upload finalizes.

Example: 245760
mimeTypestring · max: 256Read-onlyOptional

Media type recorded at upload time, used to set the download Content-Type. Present when type is file; absent for folders and for files uploaded without a declared type.

Example: image/png
descriptionstring · max: 1000Optional

Optional caller-supplied note describing the item.

Example: Quarterly financial reports
statusstring · enumRead-onlyRequired

Upload lifecycle state. A file is created pending at initiate-upload and flips to active once S3 confirms the bytes; folders are created active.

Possible values:
isSystembooleanRead-onlyRequired

When true, the platform created the item (for example a system or integration folder) and protects it — move, content replace, copy, delete, and purge are rejected with STORAGE_SYSTEM_ITEM_PROTECTED.

deletedAtstring · date-timeRead-onlyOptional

Timestamp when the item was soft-deleted to the recycle bin. Present only for recycle-bin items; the item is permanently purged 30 days after this time unless restored.

Example: 2026-04-27T10:00:00.000Z
deletedBystringRead-onlyOptional

Who soft-deleted the item — a user ID for a direct delete, or cascadeDelete for a descendant removed when its parent folder was deleted. Present only for recycle-bin items. Cascade-deleted items can be recovered only by restoring the folder that was deleted directly.

Example: 60a1b2c3d4e5f6001a2b3c4d
createdAtstring · date-timeRead-onlyRequired

Timestamp when the item was created.

Example: 2026-03-28T09:00:00.000Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp of the most recent metadata change. Updated on rename, move, and content replace, and when the folder's direct children change.

Example: 2026-03-28T14:30:00.000Z
put/v1/storage/items/{_id}
PUT /v1/storage/items/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 86

{
  "name": "quarterly-report-final.pdf",
  "description": "Updated Q1 2026 financial report"
}
{
  "_id": "683b2a0e1c3d5f001a9e8b01",
  "type": "file",
  "name": "quarterly-report-final.pdf",
  "description": "Updated Q1 2026 financial report",
  "size": 245760,
  "mimeType": "application/pdf",
  "status": "active",
  "isSystem": false,
  "createdAt": "2026-03-28T10:00:00.000Z",
  "lastModified": "2026-03-28T14:30:00.000Z"
}

Delete an item

delete
/v1/storage/items/{_id}

Soft-deletes a file or folder to the recycle bin, where it is retained for 30 days and can be restored with POST /v1/storage/items/{_id}/restore. Deleting a folder also removes its entire subtree; the folder is removed immediately and its descendants follow asynchronously. Delete is never blocked by references — flows, exports, imports, and tokens that point at the item are left dangling and fail at runtime, so check GET /v1/storage/items/{_id}/dependencies first. A pending multipart upload cannot be deleted here — cancel it with POST /v1/storage/files/{_id}/cancel.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

Item ID.

Example: 683b2a0e1c3d5f001a9e8b01
Responses
204

Item soft-deleted. For a folder, the root is removed and its descendants are removed asynchronously.

No content

delete/v1/storage/items/{_id}
DELETE /v1/storage/items/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Replace file content

patch
/v1/storage/items/{_id}/replace

Overwrites an existing file's content in place. Returns presigned upload URLs in the same shape as one initiate-upload file entry; transfer the new bytes to them just as for a new upload. The item's _id, name, and folder placement are preserved, so every reference to the file stays intact — use this instead of delete-and-recreate when a file is referenced by flows or exports. The previous content remains downloadable until the replacement finalizes. Rename with PUT /v1/storage/items/{_id} instead; this endpoint does not accept a name.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the file to replace.

Example: 683b2a0e1c3d5f001a9e8b01
Body

Requests presigned URLs to overwrite an existing file's content in place. Same shape as one initiate-upload file entry, minus name — the existing name, _id, and folder placement are preserved. Rename with PUT /v1/storage/items/{_id} instead.

mimeTypestring · max: 256Optional

New media type for the replaced content. Optional; the existing mimeType is kept when omitted.

Example: application/pdf
sizeinteger · int64Optional

Declared size in bytes of the replacement content, used to reserve quota. Reconciled to the real size when the upload finalizes.

Example: 5242880
uploadTypestring · enumRequired

How the replacement content will be transferred.

Possible values:
numPartsinteger · min: 1Optional

Number of parts the replacement will be split into. Required when uploadType is multipart.

Example: 5
uploadIdstringOptional

S3 multipart upload ID from a prior replace response. Provide with issuedPartsCount to resume and request the next batch of part URLs.

Example: abcD12efGHIjklMN3opQrst
issuedPartsCountintegerOptional

Number of part URLs already issued. Provide together with uploadId to resume an in-progress replacement.

Example: 5
Responses
200

Upload instructions for the replacement content.

application/json

Outcome for one file in an upload response. On success, statusCode is 200 and body carries the presigned-URL instructions; on failure, statusCode is a 4xx and errors explains why. Each file in a batch is validated independently, so a single response can mix successes and failures.

_idstring · objectIdOptional

ID of the pending item this result refers to. Present once the item is created; absent when the file failed validation before creation. Use it to upload, refresh URLs, cancel, or download once active.

Example: 683b2a0e1c3d5f001a9e8b01
namestringRequired

File name echoed back from the request, to correlate results.

Example: logo.png
statusCodeintegerRequired

Per-file result status, mirroring HTTP status semantics.

Example: 200
patch/v1/storage/items/{_id}/replace
PATCH /v1/storage/items/{_id}/replace HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "mimeType": "application/pdf",
  "size": 5242880,
  "uploadType": "single"
}
{
  "_id": "683b2a0e1c3d5f001a9e8b01",
  "name": "quarterly-report.pdf",
  "statusCode": 200,
  "body": {
    "uploadType": "single",
    "uploadUrl": "https://integrator-file-storage.s3.us-west-2.amazonaws.com/presigned-put-url"
  }
}

Merge a folder into another

post
/v1/storage/items/{_id}/merge

Merges the contents of a source folder into an existing destination folder, then removes the source. Runs asynchronously: the request is validated and queued, and the endpoint immediately returns 202 with a job receipt — contents move in the background and the source folder disappears once the merge completes. A soft-deleted source folder may be merged, which restores its contents into the destination. Folders only — move individual files with the move endpoint. Requires delete access on the source folder and write access on the destination.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the source folder to merge and remove.

Example: 6a6e1d9e6ac4879f0ac8006f
Body

Request body for merging a folder into another folder.

_destinationIdstring · objectIdRequired

Destination folder that receives the source folder's contents. Must reference an existing active folder that is different from the source and not one of its descendants.

Example: 6a6e1d9e7042f856e8d731ab
triggerstring · enumOptional

How the merge is recorded. Unrecognized values fall back to move. Ignored when the source folder is soft-deleted — the platform then records the merge as a restore automatically.

Default: movePossible values:
Responses
202

Merge accepted and queued. The source folder remains visible until the background job completes, then is removed.

application/json
jobIdstringRequired

Identifier of the queued merge job.

Example: f6b61847-40a8-4c74-91b6-0e641dccee13
jobTypestring · enumRequired

Kind of background job that was queued.

Possible values:
statusstring · enumRequired

Acknowledgement state of the request.

Possible values:
sourceFolderIdstring · objectIdRequired

The source folder being merged and removed.

Example: 6a6e1d9e6ac4879f0ac8006f
_destinationIdstring · objectIdRequired

The folder receiving the source folder's contents.

Example: 6a6e1d9e7042f856e8d731ab
post/v1/storage/items/{_id}/merge
POST /v1/storage/items/{_id}/merge HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "_destinationId": "6a6e1d9e7042f856e8d731ab"
}
{
  "jobId": "f6b61847-40a8-4c74-91b6-0e641dccee13",
  "jobType": "folderMerge",
  "status": "accepted",
  "sourceFolderId": "6a6e1d9e6ac4879f0ac8006f",
  "_destinationId": "6a6e1d9e7042f856e8d731ab"
}

Move an item

patch
/v1/storage/items/{_id}/move

Moves a file or folder to a different folder. Metadata only — the content stays in place, the item's _id is unchanged so references survive, and quota is unaffected. Moving a folder re-parents the folder immediately and re-anchors its descendants asynchronously, so the response reflects only the moved item itself. A folder cannot be moved into itself or one of its own descendants.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the item to move.

Example: 683b2a0e1c3d5f001a9e8b01
Body

Request body for moving an item to a different folder.

_parentIdstring · nullableRequired

Destination folder. Pass null to move the item to the account root. The key is required even when null. Must differ from the current parent, must be an active folder, and — for a folder — must not be the item itself or one of its descendants.

Example: 684c3b1f2d4e6g002b0h9c34
Responses
200

The moved item's changed fields. Only the item's own re-parenting is reflected; for a folder, descendants re-anchor asynchronously.

application/json
_idstring · objectIdRequired

ID of the moved item.

Example: 683b2a0e1c3d5f001a9e8b01
_parentIdstring · nullableOptional

New parent folder, or null if moved to the root.

Example: 684c3b1f2d4e6g002b0h9c34
__ancestorIdsstring · objectId[]Optional

New ancestor chain from the root to the parent.

Example: ["684c3b1f2d4e6g002b0h9c34"]
patch/v1/storage/items/{_id}/move
PATCH /v1/storage/items/{_id}/move HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "_parentId": "684c3b1f2d4e6g002b0h9c34"
}
{
  "_id": "683b2a0e1c3d5f001a9e8b01",
  "_parentId": "684c3b1f2d4e6g002b0h9c34",
  "__ancestorIds": [
    "684c3b1f2d4e6g002b0h9c34"
  ]
}

Copy a file

post
/v1/storage/items/{_id}/copy

Creates an independent copy of a file in a destination folder, with a new _id and its own copy of the content. Consumes quota equal to the source file's size. Files only — folder copy is not supported. Names are not deduplicated, so copying into the source's own folder without a new name produces a second file with the same name.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the file to copy.

Example: 683b2a0e1c3d5f001a9e8b01
Body

Request body for copying a file.

_destinationIdstring · nullableOptional

Destination folder for the copy. Pass null to copy to the account root. Must reference an existing active folder.

Example: 684c3b1f2d4e6g002b0h9c34
namestring · max: 256Optional

Name for the copy. Defaults to the source file's name when omitted. Duplicate names are allowed, so a copy into the source's own folder with no name produces a second file with the same name.

Example: quarterly-report-copy.pdf
Responses
201

The newly created copy.

application/json

A file or folder stored in Celigo Storage.

_idstring · objectIdRead-onlyRequired

Unique identifier for the item. Pass it to download, move, copy, replace, rename, or delete the item; folders and files share one ID space.

Example: 683b2a0e1c3d5f001a9e8b01
typestring · enumRead-onlyRequired

Distinguishes a content-bearing file from an organizational folder. Fixed when the item is created and never changes.

Possible values:
namestring · max: 256Required

Display name, including the extension for files (for example orders.csv). Two items with the same name can coexist in one folder — the name is not a unique key.

Example: logo.png
_parentIdstring · nullableRead-onlyOptional

Folder that contains this item. Null when the item sits at the account root.

Example: 683a1f2e9b0c4d001e8f7a23
__ancestorIdsstring · objectId[]Read-onlyOptional

Folder IDs from the root down to the immediate parent, in order. Empty for root-level items. Rewritten automatically when the item or any ancestor folder is moved.

Example: ["683a1f2e9b0c4d001e8f7a23"]
sizeinteger · int64Read-onlyOptional

File size in bytes. Present when type is file; folders carry no size. While an upload is pending this reflects the reserved quota, and is reconciled to the actual byte count once the upload finalizes.

Example: 245760
mimeTypestring · max: 256Read-onlyOptional

Media type recorded at upload time, used to set the download Content-Type. Present when type is file; absent for folders and for files uploaded without a declared type.

Example: image/png
descriptionstring · max: 1000Optional

Optional caller-supplied note describing the item.

Example: Quarterly financial reports
statusstring · enumRead-onlyRequired

Upload lifecycle state. A file is created pending at initiate-upload and flips to active once S3 confirms the bytes; folders are created active.

Possible values:
isSystembooleanRead-onlyRequired

When true, the platform created the item (for example a system or integration folder) and protects it — move, content replace, copy, delete, and purge are rejected with STORAGE_SYSTEM_ITEM_PROTECTED.

deletedAtstring · date-timeRead-onlyOptional

Timestamp when the item was soft-deleted to the recycle bin. Present only for recycle-bin items; the item is permanently purged 30 days after this time unless restored.

Example: 2026-04-27T10:00:00.000Z
deletedBystringRead-onlyOptional

Who soft-deleted the item — a user ID for a direct delete, or cascadeDelete for a descendant removed when its parent folder was deleted. Present only for recycle-bin items. Cascade-deleted items can be recovered only by restoring the folder that was deleted directly.

Example: 60a1b2c3d4e5f6001a2b3c4d
createdAtstring · date-timeRead-onlyRequired

Timestamp when the item was created.

Example: 2026-03-28T09:00:00.000Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp of the most recent metadata change. Updated on rename, move, and content replace, and when the folder's direct children change.

Example: 2026-03-28T14:30:00.000Z
post/v1/storage/items/{_id}/copy
POST /v1/storage/items/{_id}/copy HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "_destinationId": "684c3b1f2d4e6g002b0h9c34",
  "name": "quarterly-report-copy.pdf"
}
{
  "_id": "685d4c2g3e5f7h003c1i0d45",
  "type": "file",
  "name": "quarterly-report-copy.pdf",
  "_parentId": "684c3b1f2d4e6g002b0h9c34",
  "size": 5242880,
  "mimeType": "application/pdf",
  "description": "Q1 2026 financial report",
  "status": "active",
  "isSystem": false,
  "createdAt": "2026-04-20T10:00:00.000Z",
  "lastModified": "2026-04-20T10:00:00.000Z"
}

Restore an item

post
/v1/storage/items/{_id}/restore

Restores a soft-deleted item from the recycle bin back to its original location. Restoring a folder also restores the descendants that were removed with it; the folder comes back immediately and its descendants follow asynchronously. Only items deleted directly can be restored — a descendant removed by its parent's deletion comes back only when that parent folder is restored.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the recycle-bin item to restore.

Example: 683b2a0e1c3d5f001a9e8b01
Responses
204

Item restored. For a folder, the root is restored and its descendants follow asynchronously.

No content

post/v1/storage/items/{_id}/restore
POST /v1/storage/items/{_id}/restore HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Purge an item

delete
/v1/storage/items/{_id}/purge

Permanently deletes a soft-deleted item from the recycle bin and frees its storage. This cannot be undone. Purging a folder also purges its descendants; the folder and its subtree are removed asynchronously. Only items deleted directly can be purged — a descendant removed by its parent's deletion is purged together with that parent. The item must already be in the recycle bin.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

ID of the recycle-bin item to purge.

Example: 683b2a0e1c3d5f001a9e8b01
Responses
204

Item permanently deleted. For a folder, the subtree is purged asynchronously.

No content

delete/v1/storage/items/{_id}/purge
DELETE /v1/storage/items/{_id}/purge HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List dependencies of an item

get
/v1/storage/items/{_id}/dependencies

Returns the resources that reference this item — flows, exports, imports, MCP servers, and access tokens. These references are soft: they never block a delete or move, and go dangling if the item is removed. Check this before deleting or moving an item to see what may break.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

Item ID.

Example: 683b2a0e1c3d5f001a9e8b01
Responses
200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when nothing references the item.

application/json

Map of dependent-resource types to arrays of dependency entries. Keys are plural resource type strings (e.g. flows, imports, connections). An empty object {} means no dependents.

get/v1/storage/items/{_id}/dependencies
GET /v1/storage/items/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "flows": [
    {
      "id": "673e486ac12b3453ea0ba99a",
      "name": "Nightly export",
      "paths": [
        "pageGenerators[*]._exportId"
      ],
      "accessLevel": "manage",
      "dependencyIds": {
        "export": [
          "673e486adc497ab5e649f1ca"
        ]
      }
    }
  ]
}

Get audit log for an item

get
/v1/storageitems/{_id}/audit

Returns the change history for a storage item — creation, renames and description edits, moves, content replacements, downloads, deletes, restores, and purges — newest first. Each entry records who made the change, when, and which fields were affected.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

Item ID.

Example: 683b2a0e1c3d5f001a9e8b01
Query parameters
limitinteger · min: 1 · max: 1000Optional

Maximum number of audit entries to return per page.

Default: 1000Example: 100
afterstringOptional

Opaque pagination cursor for the next page. Take it from the after value in the Link response header's rel="next" URL rather than constructing it.

Example: W3siJGRhdGUiOiIyMDI2LTA1LTAxVDAwOjAwOjAwLjAwMFoifSwiNjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIl0
fromstring · date-timeOptional

Only return entries at or after this timestamp.

Example: 2026-05-01T00:00:00.000Z
tostring · date-timeOptional

Only return entries at or before this timestamp.

Example: 2026-05-31T23:59:59.999Z
actionstring · enumOptional

Filter by the change type. Maps to the event field on each entry.

Example: updatePossible values:
sourcestring · enumOptional

Filter by how the change was initiated.

Example: uiPossible values:
_byUserIdstring · objectIdOptional

Filter to changes performed by a single user.

Example: 624cb0346309dc3a543733a2
Responses
200

Array of audit entries, newest first.

application/json
get/v1/storageitems/{_id}/audit
GET /v1/storageitems/{_id}/audit HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
  {
    "_id": "69f63dd77009ea11abf0bce3",
    "resourceType": "storageitem",
    "_resourceId": "683b2a0e1c3d5f001a9e8b01",
    "source": "api",
    "event": "update",
    "time": "2026-05-02T18:09:26.975Z",
    "byUser": {
      "_id": "624cb0346309dc3a543733a2",
      "email": "user@example.com",
      "name": "Tyler Lamparter"
    },
    "fieldChanges": [
      {
        "fieldPath": "name",
        "oldValue": "report.pdf",
        "newValue": "quarterly-report.pdf"
      }
    ]
  }
]

Get storage usage

get
/v1/storage/usage

Returns account-wide storage usage and entitlement, aggregated across all environments: bytes in use (active and recycle bin), the licensed quota, the hard limit at which uploads are blocked, and whether the account is in overage.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
includeSystembooleanOptional

When true, also returns systemUsage — the bytes consumed by system items.

Default: falseExample: true
Responses
200

Account-wide usage and entitlement.

application/json

Account-wide storage usage and entitlement, aggregated across all environments.

activeUsageinteger · int64Required

Bytes consumed by active and pending files.

Example: 536870912
recycleBinUsageinteger · int64Required

Bytes consumed by soft-deleted files still retained in the recycle bin.

Example: 104857600
totalUsageinteger · int64Required

Sum of activeUsage and recycleBinUsage. This is the figure checked against hardLimit when an upload is attempted.

Example: 641728512
systemUsageinteger · int64Optional

Bytes consumed by system items (folders and files the platform created). Present only when the request sets includeSystem=true.

Example: 52428800
maxAllowedUsageinteger · int64Required

Storage quota in bytes granted by the account's license.

Example: 1073741824
isOveragebooleanRequired

When true, totalUsage has passed maxAllowedUsage and the account is consuming the overage buffer. Uploads still succeed until totalUsage reaches hardLimit.

hardLimitinteger · int64Required

Byte ceiling at which further uploads are rejected with STORAGE_QUOTA_EXCEEDED. Equals maxAllowedUsage plus the licensed overage buffer, or maxAllowedUsage exactly when overage is disabled.

Example: 1288490188
overageinteger · int64Required

Bytes currently consumed beyond maxAllowedUsage. Zero when not in overage.

get/v1/storage/usage
GET /v1/storage/usage HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "activeUsage": 536870912,
  "recycleBinUsage": 104857600,
  "totalUsage": 641728512,
  "systemUsage": 52428800,
  "maxAllowedUsage": 1073741824,
  "isOverage": false,
  "hardLimit": 1288490188,
  "overage": 0
}

Get storage usage by environment

get
/v1/storage/usage/environments

Returns the same account-wide totals as GET /v1/storage/usage, broken down per environment. Use it to see which environment is consuming the account's shared quota.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
includeSystembooleanOptional

When true, also returns systemUsage in the account-wide totals.

Default: falseExample: true
Responses
200

Per-environment breakdown with account-wide totals.

application/json

Per-environment usage breakdown alongside the same account-wide totals returned by GET /v1/storage/usage.

activeUsageinteger · int64Required

Account-wide bytes consumed by active and pending files.

Example: 536870912
recycleBinUsageinteger · int64Required

Account-wide bytes consumed by soft-deleted files.

Example: 104857600
totalUsageinteger · int64Required

Account-wide sum of activeUsage and recycleBinUsage.

Example: 641728512
systemUsageinteger · int64Optional

Account-wide bytes consumed by system items. Present only when the request sets includeSystem=true.

Example: 52428800
maxAllowedUsageinteger · int64Required

Storage quota in bytes granted by the account's license.

Example: 1073741824
isOveragebooleanRequired

When true, totalUsage has passed maxAllowedUsage and the account is in the overage buffer.

hardLimitinteger · int64Required

Byte ceiling at which further uploads are rejected.

Example: 1288490188
overageinteger · int64Required

Bytes currently consumed beyond maxAllowedUsage. Zero when not in overage.

get/v1/storage/usage/environments
GET /v1/storage/usage/environments HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "environments": [
    {
      "_envUserId": "60a1b2c3d4e5f6001a2b3c4d",
      "name": "Production",
      "activeUsage": 429496729,
      "recycleBinUsage": 52428800,
      "totalUsage": 481925529
    },
    {
      "_envUserId": "60a1b2c3d4e5f6001a2b3c4e",
      "name": "Sandbox",
      "activeUsage": 107374182,
      "recycleBinUsage": 52428800,
      "totalUsage": 159802982
    }
  ],
  "activeUsage": 536870912,
  "recycleBinUsage": 104857600,
  "totalUsage": 641728512,
  "maxAllowedUsage": 1073741824,
  "isOverage": false,
  "hardLimit": 1288490188,
  "overage": 0
}

Last updated

Was this helpful?