Apps
Build private React/TSX tools backed by immutable artifacts and explicit runtime tool policies. Apps execute only in caller mode: each tool call is authorized as the current caller.
/api/v1/appsAutomation triggers: view every Apps event, payload field, and predicate.
Authoring Catalog
Organization-scoped reference data for discovering App-compatible tools, dependencies, fonts, and sandbox constraints.
/api/v1/apps/catalog/toolsSearch App Tool Catalog
Search every active App-compatible ToolDef without granting permission to execute it.
Bearer caller token and X-Company-Id header required. Permission: apps:catalog:view on the organization.
Query Parameters
| Name | Type | Description |
|---|---|---|
q | string | Search text |
service_slug | string | Owning service filter |
limit | integer | Page size, max 100 |
offset | integer | Page offset |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/catalog/tools" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/catalog/dependenciesList App Dependencies
List exact package versions available to deterministic App builds, with category, license, import snippet, usage notes, and bundled peers.
Bearer caller token and X-Company-Id header required. Permission: apps:catalog:view on the organization.
curl -X GET "https://platform.ergondata.ai/api/v1/apps/catalog/dependencies" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/catalog/fontsList App Fonts
List curated self-hosted variable fonts with package imports, CSS families, and licenses.
Bearer caller token and X-Company-Id header required. Permission: apps:catalog:view on the organization.
curl -X GET "https://platform.ergondata.ai/api/v1/apps/catalog/fonts" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/catalog/constraintsGet App Constraints
Return the source, asset, bundle, browser-target, and CSP limits currently in force. These are platform settings, the same for every company, and a deployment can only lower them from the platform ceiling.
Bearer caller token and X-Company-Id header required. Permission: apps:catalog:view on the organization.
curl -X GET "https://platform.ergondata.ai/api/v1/apps/catalog/constraints" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}Apps
Private React/TSX Apps that execute with the current caller's authorization. Creation scaffolds source storage and fixed caller/platform/private modes.
/api/v1/appsList Apps
List active Apps the caller may view, or with access=use the Apps the caller may open and run. An app the caller may not view is returned without its source storage ids, draft build id, or audience count; published_version_id is still present. A member without console access may not view apps, so those fields are left out.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on each listed App, or apps:apps:use with access=use. For a member without console access, apps:apps:use is enough either way.
Query Parameters
| Name | Type | Description |
|---|---|---|
access | view | use | Permission each listed App must grant the caller (default view). Use lists exactly the Apps the caller may open, including Apps shared for use only |
tag | string[] | Require all repeated normalized tags |
managed_by | string | Lifecycle manager type; provide with managed_by_id |
managed_by_id | UUID | Lifecycle manager identifier; provide with managed_by |
platform_audience | private | shared | Limit results by explicit IAM platform audience |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | App[] | Matching Apps with platform_audience and platform_audience_grantee_count |
curl -X GET "https://platform.ergondata.ai/api/v1/apps" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/appsCreate App
Create and scaffold a private, platform-accessed, caller-authorized App in the organization.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:create on the organization.
Request Body
| Name | Type | Description |
|---|---|---|
title* | string | Title, 1–200 characters |
description | string | null | Optional description |
tags | string[] | Up to 12 tags; normalized to lowercase hyphenated identifiers |
modules | object | Modules to declare after scaffolding, instead of the default main.tsx main module. Same rules as on update. |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
tags* | string[] | Normalized App tags |
execution_mode* | "caller" | The caller-authorized execution mode |
privacy* | "private" | The MVP privacy mode |
access_mode* | "platform" | The MVP access mode |
source_version* | integer | Optimistic source version |
portal* | boolean | Whether the App is a portal of its organization: people signed out at its address sign in through its auth module |
curl -X POST "https://platform.ergondata.ai/api/v1/apps" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"title":"Case dashboard","description":"Review open cases","tags":["operations"]}'Response
201 Created{}/api/v1/apps/{app_id}Get App
Get App metadata and source/build pointers. A member without console access who may use the app gets it without its source storage ids, draft build id, or audience count; published_version_id is still present.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App; for a member without console access, apps:apps:use on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
tags* | string[] | Normalized App tags |
execution_mode* | "caller" | The caller-authorized execution mode |
privacy* | "private" | The MVP privacy mode |
access_mode* | "platform" | The MVP access mode |
source_version* | integer | Optimistic source version |
portal* | boolean | Whether the App is a portal of its organization: people signed out at its address sign in through its auth module |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/by-slug/{slug}Resolve App Address
Find the App at an address slug in the organization, the last part of its address /apps/{company_slug}/{slug}. A slug the App had before a rename still finds it until another App takes that slug, and the App's id always does; the response carries the current slug. Returned without source storage ids, draft build id, or audience count. Archived Apps, and Apps the caller may not use, are not found. Working hours, IP allowlists, and missing Apps service access still answer 403 for an App the slug finds.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:use on the App (404 without it; working hours, IP allowlists, and Apps service access answer 403).
Path Parameters
| Name | Type | Description |
|---|---|---|
slug* | string | Address slug, current or former, up to 80 characters |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
tags* | string[] | Normalized App tags |
execution_mode* | "caller" | The caller-authorized execution mode |
privacy* | "private" | The MVP privacy mode |
access_mode* | "platform" | The MVP access mode |
source_version* | integer | Optimistic source version |
portal* | boolean | Whether the App is a portal of its organization: people signed out at its address sign in through its auth module |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/by-slug/{slug}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}Update App
Update an App's title, description, tags, address slug, or modules.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
title | string | New title |
description | string | null | New description |
tags | string[] | Up to 12 tags; normalized to lowercase hyphenated identifiers |
slug | string | New address slug: lowercase letters, digits, and single hyphens, up to 80 characters, and not shaped like an App id (422), because the id opens the App too. The old slug keeps opening the App until another App takes it; archived Apps are not found at any slug. 409 when another App in the organization has it. |
modules | object | Modules declared in ergon.json. Keys you leave out are kept. The working source changes, so the draft build is cleared. A path that is not a .tsx source file inside the App and outside _dist/, or main and auth naming the same file, answers 422. 409 with code module_file_missing when the main file does not exist, and with the manifest's diagnostic code when the change conflicts with the stored manifest (for example manifest_module when auth is the current main file, or manifest_auth_requires_live on a static App). |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
tags* | string[] | Normalized App tags |
execution_mode* | "caller" | The caller-authorized execution mode |
privacy* | "private" | The MVP privacy mode |
access_mode* | "platform" | The MVP access mode |
source_version* | integer | Optimistic source version |
portal* | boolean | Whether the App is a portal of its organization: people signed out at its address sign in through its auth module |
curl -X PATCH "https://platform.ergondata.ai/api/v1/apps/{app_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"title":"Case review dashboard","modules":{"auth":"auth.tsx"}}'Response
200 OK{}/api/v1/apps/{app_id}/portalMark App as Portal
Mark or unmark the App as a portal of its organization. People signed out at a portal's address see its auth module instead of the built-in sign-in. Marking needs a published version with an auth module (409 with code portal_requires_auth_module) and an App saved to the library, one that does not expire (409 with code portal_requires_library_app). Setting the current value again changes nothing.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:manage on the App and iam:company:settings on the organization.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
portal* | boolean | true marks the App as portal; false unmarks it |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
tags* | string[] | Normalized App tags |
execution_mode* | "caller" | The caller-authorized execution mode |
privacy* | "private" | The MVP privacy mode |
access_mode* | "platform" | The MVP access mode |
source_version* | integer | Optimistic source version |
portal* | boolean | Whether the App is a portal of its organization: people signed out at its address sign in through its auth module |
curl -X PUT "https://platform.ergondata.ai/api/v1/apps/{app_id}/portal" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"portal":true}'Response
200 OK{}/api/v1/apps/portals/{company_slug}/{app_slug}/auth-moduleGet Portal Auth Module
Return the published auth module of the portal App at /apps/{company_slug}/{app_slug}, for a sign-in page shown before anyone signs in. A former slug of a renamed App answers with its current slug. Every address without a live portal App and a published auth module answers the same 404. Responses carry a weak ETag and Cache-Control: private, no-cache, and answer a matching If-None-Match with 304. Requests are rate limited per client (429).
No authentication required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_slug* | string | The organization's address slug |
app_slug* | string | The App's address slug, current or former |
Response Fields
| Name | Type | Description |
|---|---|---|
html* | string | The auth module's self-contained sandbox document |
csp* | string | Content Security Policy to apply to the frame |
title* | string | The App's title |
slug* | string | The App's current slug |
app_id* | string | The App's id; a sign-in made here is recorded with it |
version_id* | string | Published version the auth module belongs to |
curl "https://platform.ergondata.ai/api/v1/apps/portals/{company_slug}/{app_slug}/auth-module"Response
200 OK{"html":"<!doctype html>…","csp":"default-src 'none'; …","title":"Acme sign-in","slug":"sign-in","app_id":"5f0c1a2b-7d3e-4c8f-9a1b-2c3d4e5f6a7b","version_id":"ccdf98b4-a32d-4a5b-8f35-e7fe44cb55ac"}/api/v1/apps/portal-appsList Portal Apps
List the organization's portal Apps that can be an access portal, by title: marked as portal, published with an auth module, and not archived. These are the choices for the access portal of the organization (Update Company Access Portal) and of a member (Update Member Access), as app:{id}.
Bearer caller token and X-Company-Id header required. Permission: iam:company:settings or iam:company:members:manage on the organization.
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Portal Apps per page, from 1 to 200Default: 100 |
offset | integer | Portal Apps to skipDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | object[] | Portal Apps, each with id, title, and slug |
total* | integer | Total portal Apps |
limit* | integer | Current page size |
offset* | integer | Portal Apps skipped |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/portal-apps" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{"items":[{"id":"5f0c1a2b-7d3e-4c8f-9a1b-2c3d4e5f6a7b","title":"Customer Portal","slug":"customer-portal"}],"total":1,"limit":100,"offset":0}/api/v1/apps/launcherList Launcher Apps
List the published Apps the caller may use in the organization, by title: the same Apps as the apps start page. Used by an App's launcher, through the apps.launcher.list tool; inside an App, the platform adds each App's address and whether it is the App asking (current).
Bearer caller token and X-Company-Id header required. Permission: apps:apps:use on each App listed.
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Apps per page, from 1 to 200Default: 100 |
offset | integer | Apps to skipDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | object[] | Apps, each with id, title, description, and current slug |
total* | integer | Total Apps |
limit* | integer | Current page size |
offset* | integer | Apps skipped |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/launcher" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{"items":[{"id":"5f0c1a2b-7d3e-4c8f-9a1b-2c3d4e5f6a7b","title":"Orders","description":"Track orders","slug":"orders"}],"total":1,"limit":100,"offset":0}/api/v1/apps/launcher/openOpen Launcher App
Check that the caller may use the published App at a slug (current or former) or id, and return it with its current slug; 404 otherwise. Called from an App through the apps.launcher.open tool; where the calling App fills the window (its address), the platform then opens the App's address there.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:use on the App (404 without it).
Request Body
| Name | Type | Description |
|---|---|---|
slug* | string | The App's slug, a former slug, or its id; up to 80 characters |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
description* | string | null | The App's description |
slug* | string | Current slug |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/launcher/open" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"slug":"orders"}'Response
200 OK{"id":"5f0c1a2b-7d3e-4c8f-9a1b-2c3d4e5f6a7b","title":"Orders","description":"Track orders","slug":"orders"}/api/v1/apps/{app_id}Delete App
Permanently delete an active or archived App and its source tree, builds, versions, and tool policies. A portal is unmarked first.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:manage on the App; for a portal, also iam:company:settings on the organization.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X DELETE "https://platform.ergondata.ai/api/v1/apps/{app_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
204 No Content/api/v1/apps/{app_id}/archiveArchive App
Archive an App while retaining its immutable versions. A portal is unmarked, and unarchiving does not mark it again.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:manage on the App; for a portal, also iam:company:settings on the organization.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/archive" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/unarchiveUnarchive App
Restore an archived App without deleting its source or immutable versions.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:manage on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/unarchive" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/save-to-librarySave App to Library
List a conversation-managed App in My Apps and detach its conversation lifecycle ownership.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:manage on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/save-to-library" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}App Access & Connections
Manage who holds permissions on one App. Any principal IAM lists as eligible can be granted: members, teams, roles, API keys, agents, and other machine principals. IAM remains the grant and connection authority and its connection policy decides which types may connect; creator and other system-managed grants and connections remain protected.
/api/v1/apps/{app_id}/access/eligibleList Eligible App Principals
List the principals IAM allows to receive grants on this App, including members, teams, roles, API keys, agents, and other machine principals the connection policy admits.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | EligiblePrincipal[] | Eligible principals |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/eligible" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK[{"principal_type":"member","principal_id":"{member_principal_id}","label":"Sam Lee","display_name":"Sam Lee"}]/api/v1/apps/{app_id}/access/resource-typesGet App Access Catalog
Return the IAM resource-type tree and grantable permission catalog for this App. Grantable permissions are apps:apps:*, apps:apps:view, apps:apps:use, apps:apps:edit, and apps:permissions:apps:manage.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Response Fields
| Name | Type | Description |
|---|---|---|
resource_types* | ResourceTypeNode[] | Apps resource hierarchy |
permissions* | PermissionOption[] | App owner, viewer, user, and editor permission options |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/resource-types" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{"resource_types":[{"id":"{resource_type_id}","name":"App","slug":"app","parent_id":null,"children":[]}],"permissions":[{"id":"{permission_id}","name":"apps:apps:view","friendly_name":"View Apps","scope_anchor":"instance","display_order":10}]}/api/v1/apps/{app_id}/access/grantsList App Grants
List direct grants on this exact App, paged by principal: each page holds every grant of the principals on it. Any principal type is listed unless principal_types narrows it. Inherited grants and permissions outside the App access catalog are excluded; system grants are marked with is_system.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page numberDefault: 1 |
limit | integer | Principals per page, from 1 to 500Default: 100 |
principal_types | string[] | Repeatable. Only grants held by these principal types (for example member, team), applied before paging. |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | GrantEntry[] | Exact-App grants |
total* | integer | Total matching principals |
page* | integer | Current page |
limit* | integer | Current page size |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/grants" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{"items":[{"id":"{grant_id}","principal_type":"team","principal_id":"{team_principal_id}","principal_label":"Operations","permission_id":"{permission_id}","permission_name":"apps:apps:use","resource":"org/{company_id}/app/{app_id}","effect":"allow","is_system":false,"granted_at":"2026-08-27T12:00:00Z"}],"total":1,"page":1,"limit":100}/api/v1/apps/{app_id}/access/grantsCreate App Grant
Grant one principal a permission on this exact App. Grantable permissions are apps:apps:*, apps:apps:view, apps:apps:use, apps:apps:edit, and apps:permissions:apps:manage. IAM validates the caller's grant authority and rejects duplicate or unauthorized grants.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | IAM principal type: member, team, role, api_key, agent, automation, workflow, worksheet, compute_api, or channel_config |
principal_id* | string | IAM principal identifier |
permission_id* | UUID | Permission from this App's access catalog |
resource | string | null | Exact App resource path; defaults to this App |
effect | "allow" | Only allow grants are acceptedDefault: allow |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/grants" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"principal_type":"team","principal_id":"{team_principal_id}","permission_id":"{permission_id}","effect":"allow"}'Response
201 Created{"id":"{grant_id}","permission_id":"{permission_id}","name":"apps:apps:use","resource":"org/{company_id}/app/{app_id}","effect":"allow","is_system":false,"granted_at":"2026-08-27T12:00:00Z"}/api/v1/apps/{app_id}/access/grants/batchCreate App Grants Batch
Create up to 200 expanded grants with per-item results. Every resource must resolve to this exact App. Grantable permissions are apps:apps:*, apps:apps:view, apps:apps:use, apps:apps:edit, and apps:permissions:apps:manage. IAM retains final grant-authority enforcement.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
operations* | BatchGrantOperation[] | One to 200 operations; each crosses one principal with exact-App resources and catalog permission IDs, with no more than 200 expanded grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | BatchGrantResult[] | Ordered created, already_exists, or failed result for each expanded grant |
summary* | object | Counts of created, already_exists, and failed results |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/grants/batch" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"client_ref":"editors","principal_type":"team","principal_id":"{team_principal_id}","resources":["org/{company_id}/app/{app_id}"],"permission_ids":["{view_permission_id}","{edit_permission_id}"],"effect":"allow"}]}'Response
200 OK{"results":[{"index":0,"client_ref":"editors","status":"created","principal_type":"team","principal_id":"{team_principal_id}","permission_id":"{view_permission_id}","resource":"org/{company_id}/app/{app_id}","effect":"allow","grant":{"id":"{grant_id}"}}],"summary":{"created":1,"already_exists":0,"failed":0}}/api/v1/apps/{app_id}/access/grants/{grant_id}Delete App Grant
Revoke one direct grant from this exact App. Creator and other system grants cannot be revoked; IAM retains final grant-authority enforcement.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
grant_id* | string | IAM grant identifier |
curl -X DELETE "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/grants/{grant_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
204 No Content/api/v1/apps/{app_id}/access/connection-requestsList App Connection Requests
List inbound connection requests that target this exact App. IAM owns request state and applies its connection rules.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Query Parameters
| Name | Type | Description |
|---|---|---|
status | string | IAM connection-request status filterDefault: pending |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | ConnectionRequestEntry[] | Matching inbound requests |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/connection-requests" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK[{"id":"{request_id}","company_id":"{company_id}","principal_id":"{member_principal_id}","principal_label":"Sam Lee","direction":"inbound","target_service":"apps","target_resource":"org/{company_id}/app/{app_id}","requested_permissions":["apps:apps:use"],"status":"pending","created_at":"2026-08-27T12:00:00Z"}]/api/v1/apps/{app_id}/access/connection-requests/{request_id}/approveApprove App Connection Request
Approve an inbound request for this exact App. By default IAM creates the connection and grants the requested permissions. Grantable permissions are apps:apps:*, apps:apps:view, apps:apps:use, apps:apps:edit, and apps:permissions:apps:manage. IAM applies its grant-authority and connection rules.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
request_id* | string | Inbound connection request identifier |
Request Body
| Name | Type | Description |
|---|---|---|
permissions | string[] | null | Permission names to grant; defaults to the requested set |
grant | boolean | Whether IAM should issue grants during approvalDefault: true |
label | string | null | Optional connection label |
Response Fields
| Name | Type | Description |
|---|---|---|
status* | string | Updated request status |
connection_id | string | null | Created connection identifier |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/connection-requests/{request_id}/approve" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"permissions":["apps:apps:view","apps:apps:use"],"grant":true}'Response
200 OK{"id":"{request_id}","principal_id":"{member_principal_id}","target_service":"apps","target_resource":"org/{company_id}/app/{app_id}","requested_permissions":["apps:apps:use"],"status":"approved","connection_id":"{connection_id}","created_at":"2026-08-27T12:00:00Z"}/api/v1/apps/{app_id}/access/connection-requests/{request_id}/rejectReject App Connection Request
Reject an inbound request for this exact App. IAM owns the request lifecycle and enforces valid state transitions.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
request_id* | string | Inbound connection request identifier |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional rejection reason |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/connection-requests/{request_id}/reject" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"reason":"Access is not required for this team"}'Response
200 OK{"id":"{request_id}","principal_id":"{member_principal_id}","target_service":"apps","target_resource":"org/{company_id}/app/{app_id}","requested_permissions":["apps:apps:use"],"message":"Access is not required for this team","status":"rejected","created_at":"2026-08-27T12:00:00Z"}/api/v1/apps/{app_id}/access/connectionsList App Connections
List active inbound connections to this exact App, including available requester and approver provenance. IAM is the connection authority.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Response Fields
| Name | Type | Description |
|---|---|---|
[]* | InboundConnectionEntry[] | Active inbound connections |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/connections" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK[{"id":"{connection_id}","principal_id":"{team_principal_id}","principal_type":"team","principal_label":"Operations","target_service":"apps","target_resource":"org/{company_id}/app/{app_id}","label":"Operations access","system_managed_by":null,"created_at":"2026-08-27T12:05:00Z","created_by":"{approver_principal_id}","requested_by":"{requester_principal_id}"}]/api/v1/apps/{app_id}/access/connections/{connection_id}Delete App Connection
Revoke one active inbound connection from this exact App. IAM applies connection authority, lifecycle, and system-managed connection protections.
Bearer caller token and X-Company-Id header required. Permission: apps:permissions:apps:manage on the exact App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
connection_id* | string | IAM connection identifier |
curl -X DELETE "https://platform.ergondata.ai/api/v1/apps/{app_id}/access/connections/{connection_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
204 No ContentSource Files
Manage Buckets-backed source with mandatory optimistic source versions. Exact patches apply atomically.
/api/v1/apps/{app_id}/filesList Source Files
List the source tree and current optimistic source version.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/files" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/files/contentRead Source File
Read source and its digest. Binary image and font assets return base64 content.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Query Parameters
| Name | Type | Description |
|---|---|---|
path* | string | Source-relative file path |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/files/content" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/filesWrite Source File
Create or replace a source file using optimistic concurrency. Prefer Patch Source File for edits to existing files. Returns 409 when the source version is stale or expected_sha256 does not match the stored file.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
path* | string | Source-relative path |
content* | string | UTF-8 source |
expected_source_version* | integer | Current App source version |
expected_sha256 | string | null | Existing-file digest from the latest read or write of this file |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
tags* | string[] | Normalized App tags |
execution_mode* | "caller" | The caller-authorized execution mode |
privacy* | "private" | The MVP privacy mode |
access_mode* | "platform" | The MVP access mode |
source_version* | integer | Optimistic source version |
portal* | boolean | Whether the App is a portal of its organization: people signed out at its address sign in through its auth module |
path* | string | Source-relative path written |
sha256* | string | Digest of the file's new content; pass it as expected_sha256 on the next write |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/files" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"path":"App.tsx","content":"export default function App() {}","expected_source_version":3}'Response
200 OK{}/api/v1/apps/{app_id}/files/patchPatch Source File
Apply one or up to 20 exact text replacements atomically. Each search must match exactly once unless replace_all is true or a one-based occurrence is set; the two are mutually exclusive. Returns 409 for a stale source version or an unmatched/ambiguous search.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
path* | string | Source-relative path |
expected_source_version* | integer | Current App source version |
search | string | Exact text to find in single-edit mode |
replace | string | Replacement text in single-edit mode (empty deletes) |
occurrence | integer | One-based match to replace when search is not unique |
replace_all | boolean | When true, replace every match of search |
edits | array | Batch mode: 1–20 search/replace objects, each with optional replace_all or occurrence |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | App identifier |
title* | string | Display title |
tags* | string[] | Normalized App tags |
execution_mode* | "caller" | The caller-authorized execution mode |
privacy* | "private" | The MVP privacy mode |
access_mode* | "platform" | The MVP access mode |
source_version* | integer | Optimistic source version |
portal* | boolean | Whether the App is a portal of its organization: people signed out at its address sign in through its auth module |
path* | string | Source-relative path written |
sha256* | string | Digest of the file's new content; pass it as expected_sha256 on the next write |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/files/patch" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"path":"App.tsx","expected_source_version":3,"edits":[{"search":"Cases","replace":"Open cases","replace_all":true}]}'Response
200 OK{}/api/v1/apps/{app_id}/files/deleteDelete Source File
Delete a source file using optimistic concurrency. ergon.json and the files of the declared modules cannot be deleted; change modules with Update App first.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
path* | string | Source-relative path |
expected_source_version* | integer | Current App source version |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/files/delete" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"path":"src/unused.ts","expected_source_version":4}'Response
200 OK{}/api/v1/apps/{app_id}/assets/importImport App Asset
Snapshot a caller-readable Buckets image or WOFF2 font into the App source tree after format validation.
Bearer caller token and X-Company-Id header required. Permissions: apps:apps:edit on the App and read access to the source Buckets file.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
source_file_id* | UUID | Caller-readable Buckets or conversation attachment file |
path* | string | New assets/ path ending in png, jpg, jpeg, webp, svg, or woff2 |
expected_source_version* | integer | Current App source version |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/assets/import" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"source_file_id":"{file_id}","path":"assets/company-logo.png","expected_source_version":4}'Response
201 Created{}Builds, Versions & Rendering
Compile the working draft, save immutable versions, publish a selected version, and fetch sandbox envelopes.
/api/v1/apps/{app_id}/buildsBuild Draft
Compile an immutable draft snapshot on the build worker. With wait=true the request waits up to 25 seconds for diagnostics; a build that is still queued or running is returned as is, so poll Get Build until it finishes.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
wait | boolean | Wait up to 25 seconds for the worker resultDefault: true |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/builds" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"wait":true}'Response
200 OK{}/api/v1/apps/{app_id}/buildsList Builds
List builds in newest-first order.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/builds" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/builds/{build_id}Get Build
Get build status, source digest, and structured diagnostics.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
build_id* | UUID | Build identifier |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Build identifier |
status* | queued | running | succeeded | failed | Build state |
diagnostics* | object[] | Structured build diagnostics |
auth_module* | boolean | Whether it carries an auth module bundle next to the main bundle |
version_id | UUID | null | Version saved from this build, if any |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/builds/{build_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/versionsSave Version
Create an immutable version from a successful current-source build.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
build_id* | UUID | Successful build identifier |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/versions" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"build_id":"ccdf98b4-a32d-4a5b-8f35-e7fe44cb55ac"}'Response
200 OK{}/api/v1/apps/{app_id}/versionsList Versions
List immutable versions in newest-first order.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/versions" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/versions/{version_id}Get Version
Get one immutable version.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
version_id* | UUID | Version identifier |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Version identifier |
version_number* | integer | Sequential version number |
auth_module* | boolean | Whether it carries an auth module bundle next to the main bundle |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/versions/{version_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/versions/{version_id}/exportExport Version
Copy a self-contained immutable App version into a caller-writable Buckets folder.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:use on the App plus Buckets write access.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
version_id* | UUID | Version identifier |
Request Body
| Name | Type | Description |
|---|---|---|
bucket_id* | UUID | Destination Bucket identifier |
folder_id | UUID | null | Optional destination folder |
filename | string | Destination HTML filename; defaults to index.html |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/versions/{version_id}/export" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"bucket_id":"ccdf98b4-a32d-4a5b-8f35-e7fe44cb55ac","filename":"report.html"}'Response
201 Created{}/api/v1/apps/{app_id}/versions/{version_id}/filesList Version Files
List source files in an immutable version.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
version_id* | UUID | Version identifier |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/versions/{version_id}/files" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/versions/{version_id}/files/contentGet Version File
Read one source file from an immutable version.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:view on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
version_id* | UUID | Version identifier |
Query Parameters
| Name | Type | Description |
|---|---|---|
path* | string | Source-relative path |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/versions/{version_id}/files/content" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/versions/{version_id}/restoreRestore Version
Replace the working draft with an immutable version using optimistic concurrency.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
version_id* | UUID | Version identifier |
Request Body
| Name | Type | Description |
|---|---|---|
expected_source_version* | integer | Current working draft source version |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/versions/{version_id}/restore" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"expected_source_version":4}'Response
200 OK{}/api/v1/apps/{app_id}/publishPublish Version
Move the published pointer to an existing immutable version; an older version is a roll back. On a portal App the version needs an auth module (409 with code portal_requires_auth_module), and publishing one whose auth module differs from the published version's also needs the company settings permission (403 without it).
Bearer caller token and X-Company-Id header required. Permission: apps:apps:edit on the App; on a portal App whose auth module changes, also iam:company:settings on the organization.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
version_id* | UUID | Version to publish |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/publish" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"version_id":"ccdf98b4-a32d-4a5b-8f35-e7fe44cb55ac"}'Response
200 OK{}/api/v1/apps/{app_id}/renderGet Render Envelope
Return the HTML and restrictive CSP envelope for a published version or draft preview. The bridge executes authorized calls with the current caller's bearer token. Responses carry a weak ETag and Cache-Control: private, no-cache, and answer a matching If-None-Match with 304.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:use for published content or apps:apps:edit for drafts.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Query Parameters
| Name | Type | Description |
|---|---|---|
version_id | UUID | Specific immutable version |
draft | boolean | Render the current draftDefault: false |
Response Fields
| Name | Type | Description |
|---|---|---|
html* | string | Sandbox document |
csp* | string | Content Security Policy |
bridge* | "caller" | Runtime bridge mode |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/render" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}Tool Policies
Maintain the App's explicit runtime allowlist. Policies can allow a tool globally or narrow it to one exact resource or resource prefix.
/api/v1/apps/{app_id}/tool-policiesList Tool Policies
List every explicit runtime tool allowlist entry for an App.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:tool-policy:manage on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
curl -X GET "https://platform.ergondata.ai/api/v1/apps/{app_id}/tool-policies" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK{}/api/v1/apps/{app_id}/tool-policiesCreate Tool Policy
Allow one IAM-registered App tool, optionally narrowed to a resource.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:tool-policy:manage on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
tool_slug* | string | IAM-registered tool available to Apps |
resource_scope | { resource: string } | { resource_prefix: string } | null | Optional exact-resource or prefix boundary |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/tool-policies" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"tool_slug":"worksheets.rows.list","resource_scope":{"resource_prefix":"org/{company_id}/worksheet/"}}'Response
201 Created{}/api/v1/apps/{app_id}/tool-policies/{policy_id}Update Tool Policy
Replace a policy's resource scopes, argument preconditions, or enforced filters.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:tool-policy:manage on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
policy_id* | UUID | Policy identifier |
Request Body
| Name | Type | Description |
|---|---|---|
resource_scopes | array | null | Up to 20 exact-resource or prefix boundaries |
preconditions | array | null | Up to 20 mandatory argument conditions |
enforced_filters | object | null | Mandatory structured filters appended at runtime |
curl -X PATCH "https://platform.ergondata.ai/api/v1/apps/{app_id}/tool-policies/{policy_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"resource_scopes":[{"resource_prefix":"org/{company_id}/workflow/"}]}'Response
200 OK{}/api/v1/apps/{app_id}/tool-policies/{policy_id}Delete Tool Policy
Remove a tool from the App runtime allowlist.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:tool-policy:manage on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
policy_id* | UUID | Policy identifier |
curl -X DELETE "https://platform.ergondata.ai/api/v1/apps/{app_id}/tool-policies/{policy_id}" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
204 No ContentCaller-Authorized Runtime Tools
The sandbox can preflight or invoke only explicitly allowed tools. Every call rechecks the current caller's IAM capability and forwards that caller's bearer token.
/api/v1/apps/{app_id}/tools/checkCheck Tool Calls
Preflight up to 50 proposed calls against App policies and the current caller's IAM permissions.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:use on the App.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
Request Body
| Name | Type | Description |
|---|---|---|
calls* | array | One to 50 objects with a tool slug and argument object |
Response Fields
| Name | Type | Description |
|---|---|---|
decisions* | ToolCheckDecision[] | Per-call allow decision, reason, permission, and resource |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/tools/check" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"calls":[{"slug":"worksheets.rows.list","args":{"worksheet_id":"{worksheet_id}"}}]}'Response
200 OK{}/api/v1/apps/{app_id}/tools/{slug}/invokeInvoke Tool
Invoke one explicitly allowed tool after rechecking the current caller. The downstream status, body, and content type are passed through.
Bearer caller token and X-Company-Id header required. Permission: apps:apps:use on the App plus the downstream tool capability.
Path Parameters
| Name | Type | Description |
|---|---|---|
app_id* | UUID | App identifier |
slug* | string | Registered tool slug |
Request Body
| Name | Type | Description |
|---|---|---|
args | object | Arguments for the downstream tool |
curl -X POST "https://platform.ergondata.ai/api/v1/apps/{app_id}/tools/{slug}/invoke" \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}" \
-H "Content-Type: application/json" \
-d '{"args":{"worksheet_id":"{worksheet_id}"}}'Response
200 OK{}