@archastro/sdk
    Preparing search index...

    Class SolutionResource

    Index

    Constructors

    constructor

    Methods

    create delete dependents get install list readme upgrade

    Constructors

    Methods

    • Import a Solution into the library Imports a Solution and its bundled configs (skills, scripts, templates, files) into the library for the target scope. Two mutually exclusive import modes are supported: pass solution to re-import an existing system-owned catalog Solution by ID or lookup_key, or pass solution_bundle to supply a self-contained inline bundle. Exactly one must be present. The operation upserts the bundle in a single transaction. When dry_run is true the same pipeline runs but the transaction is rolled back — no rows are persisted and the response reflects what would have been written. The response shape is the same in both cases: the Solution summary plus installed_configs listing each config the import created or would create. Pairs with POST /api/v1/solutions/:solution/install: this endpoint puts the Solution into the library; install provisions a runtime resource (Agent, AgentRoutine, AgentTool, etc.) from an already-imported Solution.

      Parameters

      • input: {
            dry_run?: boolean;
            org?: string;
            solution?: string;
            solution_bundle?: {
                configs?: {
                    content: string;
                    content_type?: string;
                    relative_path: string;
                }[];
                lookup_key_prefix?: string;
                lookup_key_suffix?: string;
                setup_actions?: {
                    depends_on?: string[];
                    description?: string;
                    kind: string;
                    params?: Record<string, unknown>;
                    required?: boolean;
                    sort_order?: number;
                    title: string;
                    verify_config?: Record<string, unknown>;
                }[];
                skills?: {
                    content: string;
                    content_type?: string;
                    files?: { content: string; content_type?: string; relative_path: string }[];
                    relative_path: string;
                }[];
                solution: {
                    content: string;
                    content_type?: string;
                    files?: {
                        content: string;
                        content_type?: string;
                        data_encoding?: string;
                        relative_path: string;
                    }[];
                    lookup_key: string;
                };
                template?: {
                    content: string;
                    content_type?: string;
                    relative_path: string;
                };
                templates?: {
                    content: string;
                    content_type?: string;
                    relative_path: string;
                }[];
            };
            team?: string;
            user?: string;
            virtual_path_prefix?: string;
        }

        Request body.

        • Optionaldry_run?: boolean

          When true, runs the full import pipeline but rolls back the transaction — no rows are persisted. The response reflects what would have been written. Defaults to false.

        • Optionalorg?: string

          Organization ID (org_...) for the import destination scope.

        • Optionalsolution?: string

          Config ID (cfg_...) or lookup_key of an existing system-owned, org-less Solution to import into the target scope. Mutually exclusive with solution_bundle.

        • Optionalsolution_bundle?: {
              configs?: {
                  content: string;
                  content_type?: string;
                  relative_path: string;
              }[];
              lookup_key_prefix?: string;
              lookup_key_suffix?: string;
              setup_actions?: {
                  depends_on?: string[];
                  description?: string;
                  kind: string;
                  params?: Record<string, unknown>;
                  required?: boolean;
                  sort_order?: number;
                  title: string;
                  verify_config?: Record<string, unknown>;
              }[];
              skills?: {
                  content: string;
                  content_type?: string;
                  files?: { content: string; content_type?: string; relative_path: string }[];
                  relative_path: string;
              }[];
              solution: {
                  content: string;
                  content_type?: string;
                  files?: {
                      content: string;
                      content_type?: string;
                      data_encoding?: string;
                      relative_path: string;
                  }[];
                  lookup_key: string;
              };
              template?: {
                  content: string;
                  content_type?: string;
                  relative_path: string;
              };
              templates?: {
                  content: string;
                  content_type?: string;
                  relative_path: string;
              }[];
          }

          Self-contained inline bundle containing the Solution metadata plus all bundled configs (skills, templates, configs, files). Mutually exclusive with solution.

        • Optionalteam?: string

          Team ID (team_...) for the import destination scope.

        • Optionaluser?: string

          User ID (usr_...) for the import destination scope. Only one of org, team, or user may be set.

        • Optionalvirtual_path_prefix?: string

          Path prefix under which all uploaded configs' virtual_path values are anchored (for example solutions/<uuid>). Stable per install; omit to use no prefix.

      Returns Promise<SolutionImportResponse>

      The imported Solution in summary form, plus installed_configs — one entry per config the transaction created or would create in dry_run mode. installed_configs is deprecated; prefer the solution summary shape for new integrations.

    • Delete a Solution Permanently deletes an imported Solution and all configs bundled with it, including templates, skills, scripts, and files. The deletion runs in a single transaction; provider-stored blobs are swept asynchronously after commit. Org-scope callers (for example, an org admin in the Library settings page) can only delete their org's copy of the Solution. App-scope callers can delete Solutions at either scope. RBAC is enforced inside the core delete flow. Returns 204 No Content on success.

      Parameters

      • solution: string

        Solution config ID (cfg_...) or lookup_key of the Solution to delete.

      Returns Promise<void>

      Empty body. HTTP 204 indicates the Solution was deleted successfully.

    • Preview Solution delete impact Returns a read-only preview of what deleting the specified Solution would affect: the agents that reference the Solution's bundle, and the count of bundled configs that would be orphaned rather than cascade-deleted. Use this endpoint before calling DELETE /api/v1/solutions/:solution to surface a warning when live agents depend on the Solution. Visibility scope mirrors the delete endpoint: org-scope viewers see their org's copy; app-scope viewers can inspect either scope.

      Parameters

      • solution: string

        Solution config ID (cfg_...) or lookup_key of the Solution to inspect.

      Returns Promise<SolutionDependentsResponse>

      Agents that reference this Solution's bundle plus the count of configs that would be orphaned on delete.

    • Retrieve a Solution Returns a single Solution identified by its config ID (cfg_...) or lookup_key, in the same summary shape the list endpoint emits. The response always includes a freshly-minted readme_url — call this endpoint to refresh an expired README token without making any other state change. Visibility matches the list endpoint: app-level Solutions (no org affiliation) are visible to everyone — including unauthenticated callers, so the public catalog can render a Solution's detail page logged-out; org-scoped Solutions are only visible to authenticated viewers whose org context matches. Anything else returns 404. When the resolved Solution is org-scoped, the endpoint compares its solution_version against the matching app-level copy. If the app-level copy is at a higher version the response includes upgrade_available: true and latest_version. App-level resolutions always report upgrade_available: false.

      Parameters

      • solution: string

        Solution config ID (cfg_...) or lookup_key of the Solution to retrieve.

      Returns Promise<SolutionSummary>

      Solution summary including a freshly-minted readme_url token valid for one hour.

    • Install a Solution Provisions a runtime resource from an already-imported Solution. The type of resource created depends on the template the Solution wraps: an AgentTemplate produces an Agent, an AutomationTemplate produces an Automation, and attachment templates (AgentRoutineTemplate, AgentToolTemplate, AgentSkillTemplate, AgentComputerTemplate) attach a sub-resource to an existing Agent specified by target. For Solutions that bundle more than one template, pass template (the ID or lookup_key of the desired template) to select which one to provision. Single-template Solutions do not require template. Pairs with POST /api/v1/solutions (import): import puts the Solution into the library; install provisions a runtime resource from it.

      Parameters

      • solution: string

        Config ID (cfg_...) or lookup_key of the already-imported Solution to install from.

      • input: {
            allow_auto_import?: boolean;
            lookup_key?: string;
            lookup_key_suffix?: string;
            name?: string;
            org?: string;
            target?: string;
            team?: string;
            template?: string;
            user?: string;
        }

        Request body.

        • Optionalallow_auto_import?: boolean

          When true, automatically imports the Solution into the target tenant before installing if the org-scoped copy does not yet exist. Requires either an authenticated org user (member or admin) or a platform-privileged caller (S2S, developer JWT) that also supplies an explicit org param. Defaults to false; without it the endpoint returns 404 when the org-scoped Solution is missing.

        • Optionallookup_key?: string

          Lookup key override for the provisioned resource (for example, the Agent's agent_key).

        • Optionallookup_key_suffix?: string

          Suffix appended to every config_ref: resolution at install time. Should be stable per logical install and unique per attempt — allows the same Solution to be installed multiple times in the same app without collisions.

        • Optionalname?: string

          Display name override for the provisioned Agent. Ignored for non-Agent Solutions.

        • Optionalorg?: string

          Organization ID (org_...) for the install destination scope.

        • Optionaltarget?: string

          ID or lookup_key of the parent Agent to attach to. Required when installing an AgentRoutineTemplate, AgentToolTemplate, AgentSkillTemplate, or AgentComputerTemplate Solution, since those produce sub-resources attached to an existing Agent. Omit for AgentTemplate and AutomationTemplate Solutions, which provision standalone resources.

        • Optionalteam?: string

          Team ID (team_...) for the install destination scope.

        • Optionaltemplate?: string

          Config ID (cfg_...) or lookup_key of the template within the Solution to provision. Required when the Solution bundles more than one template; omit for single-template Solutions, where the only template is selected implicitly.

        • Optionaluser?: string

          User ID (usr_...) for the install destination scope.

      Returns Promise<SolutionInstallResponse>

      The provisioned runtime resource (Agent, Automation, AgentRoutine, AgentTool, AgentSkill, or AgentComputer) together with the source Solution's config ID.

    • List Solutions Returns a paginated list of Solutions visible to the caller, merging two scopes: app-level Solutions (system-owned rows with no org affiliation, visible to everyone — including unauthenticated callers — so they can power the public catalog) and org-level Solutions (system-owned rows stamped with the viewer's org ID, included when an authenticated viewer carries an org context). Unauthenticated callers resolve to an app-scoped anonymous viewer and therefore only ever see the app-level scope. Solutions that appear under both scopes are deduplicated by their stable solution_id value. The merged entry's owners array lists every scope the Solution was found under ("system" and/or "org"). When the app-level copy has a higher solution_version than the org-level copy, the response includes upgrade_available: true and latest_version so callers can prompt for an upgrade.

      Parameters

      • Optionalparams: {
            lookupKey?: string;
            owners?: string[];
            page?: number;
            pageSize?: number;
            pathPrefix?: string;
        }

        Query parameters.

        • OptionallookupKey?: string

          Filter to the Solution whose lookup_key matches exactly.

        • Optionalowners?: string[]

          Restrict results to a subset of owner scopes. Accepted values: "system" (app-level Solutions) and "org" (viewer's org-level Solutions). Omit to include all scopes the viewer can see.

        • Optionalpage?: number

          Page number to return. Defaults to 1.

        • OptionalpageSize?: number

          Number of Solutions per page. Defaults to 25.

        • OptionalpathPrefix?: string

          Filter to Solutions whose virtual_path starts with this prefix.

      Returns Promise<SolutionListResponse>

      Paginated list of Solution summaries visible to the caller.

    • Retrieve a Solution README or asset Serves the README markdown or a bundled asset for an imported Solution. Both modes use the same path and require a short-lived signed token in the query string rather than an Authorization header, so browsers can load asset URLs directly from <img src> attributes without custom request logic. When file is omitted the response is the Solution's readme field rendered as text/markdown. All local asset references in the markdown are rewritten to point back at this endpoint with ?file=PATH&token=TOKEN so browsers can load images inline without additional authentication. When file is set the response is the raw bytes of the matching asset (a File child whose relative_path equals PATH, or an inline assets entry by name) with the asset's stored Content-Type. Tokens are scoped to a single Solution, carry the viewer's app, org, and sandbox context from the time they were minted, and expire after one hour. Obtain a fresh token by calling GET /api/v1/solutions/:solution, which always returns a newly minted readme_url.

      Parameters

      • solution: string

        Solution config ID (cfg_...) identifying the Solution whose README or asset to retrieve.

      • Optionalparams: { file?: string; token?: string }

        Query parameters.

        • Optionalfile?: string

          Relative path of the asset to retrieve (for example images/hero.png). When present the response is the raw asset bytes with its real Content-Type; when absent the response is the README markdown.

        • Optionaltoken?: string

          Signed URL token minted by the list or show endpoint. Expires after one hour.

      Returns Promise<{ content: ArrayBuffer; mimeType: string }>

      README markdown (text/markdown) when file is omitted, or the raw asset bytes with the asset's Content-Type when file is set.

    • Upgrade an installed Solution Applies an incoming bundle to an already-installed Solution in a single atomic transaction, bringing its configs in line with the new bundle. Config IDs are preserved across the upgrade. Configs that existed in the old bundle but are absent from the new one are orphaned (top-level) or hard-deleted (child rows). Two mutually exclusive source modes: pass target_solution to pull the incoming bundle from an existing Solution by ID or lookup_key, or pass solution_bundle to supply a complete inline bundle directly. Exactly one must be present. When dry_run is true the full diff is computed and returned but no changes are written. Pass the dry-run response's review_fingerprint as expected_review_fingerprint when applying to guard against the bundle changing between review and apply.

      Parameters

      • solution: string

        Config ID (cfg_...) or lookup_key of the currently installed Solution to upgrade.

      • input: {
            allow_downgrade?: boolean;
            dry_run?: boolean;
            expected_review_fingerprint?: string;
            org?: string;
            solution_bundle?: {
                configs?: {
                    content: string;
                    content_type?: string;
                    relative_path: string;
                }[];
                lookup_key_prefix?: string;
                lookup_key_suffix?: string;
                setup_actions?: {
                    depends_on?: string[];
                    description?: string;
                    kind: string;
                    params?: Record<string, unknown>;
                    required?: boolean;
                    sort_order?: number;
                    title: string;
                    verify_config?: Record<string, unknown>;
                }[];
                skills?: {
                    content: string;
                    content_type?: string;
                    files?: { content: string; content_type?: string; relative_path: string }[];
                    relative_path: string;
                }[];
                solution: {
                    content: string;
                    content_type?: string;
                    files?: {
                        content: string;
                        content_type?: string;
                        data_encoding?: string;
                        relative_path: string;
                    }[];
                    lookup_key: string;
                };
                template?: {
                    content: string;
                    content_type?: string;
                    relative_path: string;
                };
                templates?: {
                    content: string;
                    content_type?: string;
                    relative_path: string;
                }[];
            };
            target_solution?: string;
        }

        Request body.

        • Optionalallow_downgrade?: boolean

          When true, permits an incoming solution_version lower than the currently installed version. Defaults to false.

        • Optionaldry_run?: boolean

          When true, computes and returns the full upgrade diff without persisting any changes. Defaults to false.

        • Optionalexpected_review_fingerprint?: string

          Optional stale-review guard. Pass the review_fingerprint returned by a prior dry_run call to ensure the bundle has not changed between review and apply.

        • Optionalorg?: string

          Organization ID (org_...) used to resolve org-scoped lookup_key values. Config IDs (cfg_...) are globally unique and do not require this.

        • Optionalsolution_bundle?: {
              configs?: {
                  content: string;
                  content_type?: string;
                  relative_path: string;
              }[];
              lookup_key_prefix?: string;
              lookup_key_suffix?: string;
              setup_actions?: {
                  depends_on?: string[];
                  description?: string;
                  kind: string;
                  params?: Record<string, unknown>;
                  required?: boolean;
                  sort_order?: number;
                  title: string;
                  verify_config?: Record<string, unknown>;
              }[];
              skills?: {
                  content: string;
                  content_type?: string;
                  files?: { content: string; content_type?: string; relative_path: string }[];
                  relative_path: string;
              }[];
              solution: {
                  content: string;
                  content_type?: string;
                  files?: {
                      content: string;
                      content_type?: string;
                      data_encoding?: string;
                      relative_path: string;
                  }[];
                  lookup_key: string;
              };
              template?: {
                  content: string;
                  content_type?: string;
                  relative_path: string;
              };
              templates?: {
                  content: string;
                  content_type?: string;
                  relative_path: string;
              }[];
          }

          Complete inline bundle for a direct upgrade, including Solution metadata, templates, skills, configs, files, and setup actions. Mutually exclusive with target_solution.

        • Optionaltarget_solution?: string

          Config ID (cfg_...) or lookup_key of the Solution to use as the incoming upgrade source. Mutually exclusive with solution_bundle.

      Returns Promise<SolutionUpgradeResponse>

      Updated Solution plus the full upgrade diff.

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods