Connect

Connect apps, versions, and scripts used to build integrations with external systems.

📄️ Add Connect App

Creates a Connect app owned by the authenticated user's current company, which must grant the `app:manage` permission. The new app always starts with `status` `development` (hidden from other companies), no permissions, and a draft version `1.0.0` ready for the scripts that `terros connect publish` uploads. `description` is a short markdown summary. Use the returned `appId` as `appId` in the app's `terros.json`, and `/connect/app/update` to change the app afterwards.

📄️ Get Connect App

Retrieves one Connect app by `appId` along with its versions. Published apps are visible to everyone; otherwise the `app:list` permission on the app's owning company is required. Only deployed versions are returned unless you have the `app:manage` permission on the owning company. Use `/connect/app/version/get` to get the scripts attached to a specific version.

📄️ List Connect Apps

Lists Connect apps. With no filter it returns the apps owned by the authenticated user's current company plus every published app, which are the apps that company can install. Pass `companyId` to list only that company's own apps, which requires the `app:list` permission on it. Filtering by `validationStatus` is for Terros staff only.

📄️ Get Connect App Logs

Retrieves the log lines one Connect script (`scriptId`) wrote while it ran, oldest first, for example to confirm that a new install's script ran. Pass `installId` to see only that install's company's runs, which requires the `install:manage` permission on the install's company. Passing `appId` instead returns runs across every company, optionally narrowed with `companyId`, and is for Terros staff only. Pass `filter` to return only lines containing that exact text (case-sensitive), for example an error message; it works with `installId`, `appId` and `companyId`, and with `startTime` and `endTime` to set the time range. Defaults to the last 30 days; page with `nextToken`. A filtered page can hold fewer than `limit` lines, or none, while `nextToken` is still set, so keep paging until it is absent.

📄️ Update Connect App

Updates a Connect app such as its `name`, `description` or `status`. Only `appId` is required: send just the fields to change, and every field left out keeps its stored value. The app's owning company cannot be changed: a `companyId` other than the app's current one is rejected with `InvalidRequest`. Use `/connect/app/copy` to copy an app into another company. Requires the `app:manage` permission on the app's owning company. Setting `status` to `published` requires an approved marketplace review and a deployed, non-archived current version. The response's `uploadAvatarUrl` is a temporary URL: upload the app's logo image to it with an HTTP `PUT` and the image's `Content-Type`.

📄️ Get Connect App Version

Retrieves one Connect app version, identified by `appId` and `appVersion`, along with the scripts attached to that version. Users with the `app:manage` permission on the owning company can see any version; others can only see deployed versions of apps they can view. Use `/connect/app/get` to list all versions of an app.

📄️ Update Connect App Version

Updates a Connect app version. Draft versions can be freely edited; setting `status` to `deployed` makes the version and its scripts live and, if it is the newest version, makes it the app's current version. After deployment the only allowed change is setting `status` to `deprecated`, which is not allowed for the current version of a published app. Requires the `app:manage` permission on the app's owning company.