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.

Base URL/api/v1/apps

Automation 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.

GET/api/v1/apps/catalog/tools

Search 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

{}

GET/api/v1/apps/catalog/dependencies

List App Dependencies

List exact package versions available to deterministic App builds.

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

{}

GET/api/v1/apps/catalog/fonts

List 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

{}

GET/api/v1/apps/catalog/constraints

Get App Constraints

Return source, asset, bundle, browser-target, and CSP constraints.

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.

GET/api/v1/apps

List Apps

List active Apps visible to the caller.

Bearer caller token and X-Company-Id header required. Permission: apps:apps:view.

Query Parameters

Name	Type	Description
`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[]	Visible 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

{}

POST/api/v1/apps

Create 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

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

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

{}

GET/api/v1/apps/{app_id}

Get App

Get App metadata and source/build pointers.

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

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

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

{}

PATCH/api/v1/apps/{app_id}

Update App

Update an App's editable title or description.

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

Request Body

Name	Type	Description
`title`	string	New title
`description`	string \| null	New description

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"}'

Response

200 OK

{}

DELETE/api/v1/apps/{app_id}

Delete App

Permanently delete an active or archived App and its source tree, builds, versions, and tool policies.

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 DELETE "https://platform.ergondata.ai/api/v1/apps/{app_id}" \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

204 No Content

POST/api/v1/apps/{app_id}/archive

Archive App

Archive an App while retaining its 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}/archive" \
  -H "Authorization: Bearer {token}" \
  -H "X-Company-Id: {company_id}"

Response

200 OK

{}

POST/api/v1/apps/{app_id}/unarchive

Unarchive 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

{}

POST/api/v1/apps/{app_id}/save-to-library

Save 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 the platform audience for one App. This surface accepts only member and team principals and only App view, use, and edit permissions. IAM remains the grant and connection authority; creator and other system-managed grants and connections remain protected.

GET/api/v1/apps/{app_id}/access/eligible

List Eligible App Principals

List connected platform members and teams that are eligible to receive grants on this App. App principals and public or external identities are not returned.

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 platform members and teams

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"}]

GET/api/v1/apps/{app_id}/access/resource-types

Get 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}]}

GET/api/v1/apps/{app_id}/access/grants

List App Grants

List direct grants for platform members and teams on this exact App. Inherited grants and permissions outside App view, use, and edit 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	Items per page, from 1 to 500Default: `100`

Response Fields

Name	Type	Description
`items`*	GrantEntry[]	Exact-App grants
`total`*	integer	Total matching grants
`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}

POST/api/v1/apps/{app_id}/access/grants

Create App Grant

Grant one platform member or team 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`*	"member" \| "team"	Platform audience type
`principal_id`*	string	Member or team 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"}

POST/api/v1/apps/{app_id}/access/grants/batch

Create App Grants Batch

Create up to 200 expanded member or team 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 member or team 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}}

DELETE/api/v1/apps/{app_id}/access/grants/{grant_id}

Delete App Grant

Revoke one direct member or team 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

GET/api/v1/apps/{app_id}/access/connection-requests

List App Connection Requests

List inbound connection requests from platform members and teams 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 member and team 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"}]

POST/api/v1/apps/{app_id}/access/connection-requests/{request_id}/approve

Approve App Connection Request

Approve an inbound member or team 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"}

POST/api/v1/apps/{app_id}/access/connection-requests/{request_id}/reject

Reject App Connection Request

Reject an inbound member or team 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"}

GET/api/v1/apps/{app_id}/access/connections

List App Connections

List active inbound member and team 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 member and team 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}"}]

DELETE/api/v1/apps/{app_id}/access/connections/{connection_id}

Delete App Connection

Revoke one active inbound member or team 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 Content

Source Files

Manage Buckets-backed source with mandatory optimistic source versions. Exact patches apply atomically.

GET/api/v1/apps/{app_id}/files

List 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

{}

GET/api/v1/apps/{app_id}/files/content

Read 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

{}

POST/api/v1/apps/{app_id}/files

Write 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
`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

{}

POST/api/v1/apps/{app_id}/files/patch

Patch 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
`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

{}

POST/api/v1/apps/{app_id}/files/delete

Delete Source File

Delete a non-canonical source file 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

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

{}

POST/api/v1/apps/{app_id}/assets/import

Import 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.

POST/api/v1/apps/{app_id}/builds

Build Draft

Compile an immutable draft snapshot. With wait=true, diagnostics are returned inline.

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

{}

GET/api/v1/apps/{app_id}/builds

List 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

{}

GET/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

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

{}

POST/api/v1/apps/{app_id}/versions

Save 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

{}

GET/api/v1/apps/{app_id}/versions

List 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

{}

GET/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

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

{}

POST/api/v1/apps/{app_id}/versions/{version_id}/export

Export 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

{}

GET/api/v1/apps/{app_id}/versions/{version_id}/files

List 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

{}

GET/api/v1/apps/{app_id}/versions/{version_id}/files/content

Get 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

{}

POST/api/v1/apps/{app_id}/versions/{version_id}/restore

Restore 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

{}

POST/api/v1/apps/{app_id}/publish

Publish Version

Move the published pointer to an existing immutable version.

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
`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

{}

GET/api/v1/apps/{app_id}/render

Get 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.

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.

GET/api/v1/apps/{app_id}/tool-policies

List 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

{}

POST/api/v1/apps/{app_id}/tool-policies

Create 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

{}

PATCH/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

{}

DELETE/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 Content

Caller-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.

POST/api/v1/apps/{app_id}/tools/check

Check 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

{}

POST/api/v1/apps/{app_id}/tools/{slug}/invoke

Invoke 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

{}