Modules API

Modules are catalogue entries in Hutly’s internal authoring organization that bundle an app site and/or workflow roots as a single installable unit. See Modules for the concept and the CLI reference for the hutly modules command group.

Register a module

Registers a new module version (upserts by slug). Each root must reference an app site or workflow that already exists in the authoring org and carries its own description.

POST /orgs/{organizationId}/modules

Request body:

{
  "slug": "acme-portal",
  "name": "Acme Portal",
  "description": "Bundles the Acme storefront site with its nightly sync workflow.",
  "visibility": "public",
  "category": "e-commerce",
  "tags": ["portal", "acme"],
  "roots": [
    { "kind": "app_site", "resourceId": "3f9e2b3a-2222-4c11-9b8e-111111111111", "description": "the storefront" },
    { "kind": "workflow", "resourceId": "7c1d44f0-3333-4d22-8c9f-222222222222", "description": "nightly sync" }
  ]
}

visibility defaults to public; category and tags are optional.

List modules

Returns the platform-wide public catalogue — every public module regardless of authoring org — plus the calling organization’s own modules if it is an authoring org.

GET /orgs/{organizationId}/modules

Get a module

Fetches a single module by id, including its roots.

GET /orgs/{organizationId}/modules/{moduleId}

Get a module’s source bundle

Returns the module’s full source bundle — every resource it bundles (app sites, apps, workflows, tables, agents, knowledge bases) plus a presigned S3 URL per app artifact. This is the payload hutly modules project projects into a portable YAML tree.

GET /orgs/{organizationId}/modules/{moduleId}/source

Activation

Bringing a module into a consumer org runs through an activation session — a stepped resource that moves preview → holes → configure → accepted → deploying → done/failed. See Modules for the concept and the CLI reference for the hutly modules activation / hutly modules activate commands.

A session has one of two snapshot origins:

• registry — the session snapshots the module as currently registered in the catalogue.
• uploaded — the session snapshots a bundle supplied in the begin request body (an uploaded, possibly Sammy-edited, module tree).

Begin an activation session

Starts a session for moduleId and returns its id plus a preview (module summary, unresolved holes, and the derived app_site slug). Registry-origin activation omits the body; uploaded-origin activation supplies bundle.

POST /orgs/{organizationId}/modules/{moduleId}/activations

Request body (optional, uploaded origin only):

{
  "bundle": { "module": { "...": "..." }, "workflows": [], "agents": [] }
}

Response:

{
  "sessionId": "7c1d44f0-3333-4d22-8c9f-222222222222",
  "preview": {
    "module": { "name": "Acme Portal", "description": "...", "version": 3 },
    "holes": [],
    "derivedSlug": "acme-portal"
  }
}

Get an activation session

GET /orgs/{organizationId}/activations/{sessionId}

Returns the full ActivationSession, including its current step.

Recompute holes

Recomputes and returns the session’s unresolved holes (secrets/integrations still required before accept will succeed).

POST /orgs/{organizationId}/activations/{sessionId}/holes

Configure an activation session

Sets the app_site slug and any params for the module being activated. slug is omitted for workflow-only modules (no app_site to slug).

POST /orgs/{organizationId}/activations/{sessionId}/configure

Request body:

{
  "slug": "acme-portal",
  "params": { "region": "au" }
}

Accept an activation session

Advances the session to accepted. This is a strict gate: it returns 409 activation_holes_unresolved if any holes remain unresolved.

POST /orgs/{organizationId}/activations/{sessionId}/accept

Deploy an activation session

Starts the async clone of the module’s resources into the org, moving the session to deploying. Returns 409 activation_not_accepted if the session hasn’t reached accepted yet. Poll GET .../activations/{sessionId} to watch progress to done or failed.

POST /orgs/{organizationId}/activations/{sessionId}/deploy

Response:

{ "ok": true }

Hide / unhide an activated module

Toggle an activated module’s visibility for the org without deactivating it.

POST /orgs/{organizationId}/modules/{moduleId}/hide
POST /orgs/{organizationId}/modules/{moduleId}/unhide

Both return the org’s ModuleActivation record with its updated state (hidden or active).