Developers
← All documentationContents ↓

API Reference: Solutions

List, preview, apply, inspect, update, and detach first-party Collection Solutions through seven public-ID-only contracts.

Overview

Solutions are versioned first-party recipes that configure ordinary Simply360 assets for one exact Data Collection. The API exposes a schema-versioned catalog and reviewed lifecycle. Preview is non-mutating; apply recomputes and atomically commits the exact reviewed asset plan.

Every request and response uses public Simply IDs. Numeric database IDs are never accepted or returned. The wire schema version is simply360.solutions-api/v1, and configuration uses simply360.solution-configuration/v1.

Authentication and Authority

Catalog and installation reads are standard-tier operations. A team API key or OAuth token needs schema:read plus access to the exact Team and Collection. Responses omit inaccessible candidates, fields, assets, and configuration.

The two preview POST operations are read-only and accept either Cognito or a user-bound OAuth token with schema:read when the resolved actor is an active Team Admin. The three mutation POST operations—apply, apply-update, and detach—are Cognito-only and require an active Team Admin, or an authenticated System Admin using the existing support boundary. API keys and OAuth service principals cannot preview or mutate Solutions and receive a stable unsupported-principal denial. This V1 authority will be extended by the separately reviewed delegated Team User policy; clients must not assume every Team User is permanently excluded.

Endpoints

MethodPathSDKPurpose
GET/v1/data-collections/{dataCollectionSimplyId}/solutionss360.solutions.list(...)List the Collection catalog and compatibility evidence.
POST/v1/data-collections/{dataCollectionSimplyId}/solutions/{solutionKey}/previews360.solutions.preview(...)Return normalized configuration and an exact non-mutating review.
POST/v1/data-collections/{dataCollectionSimplyId}/solutions/{solutionKey}/applys360.solutions.apply(...)Atomically apply a blocker-free reviewed installation.
GET/v1/solutions/{teamSolutionInstallationSimplyId}s360.solutions.get(...)Inspect one installation, asset state, drift, and safe runtime evidence.
POST/v1/solutions/{teamSolutionInstallationSimplyId}/preview-updates360.solutions.previewUpdate(...)Preview a friendly update.
POST/v1/solutions/{teamSolutionInstallationSimplyId}/apply-updates360.solutions.applyUpdate(...)Atomically apply the reviewed friendly update.
POST/v1/solutions/{teamSolutionInstallationSimplyId}/detachs360.solutions.detach(...)Detach management while keeping canonical assets and history.

List the Collection Catalog

const catalog = await s360.solutions.list('DCL1-2345-6789');

for (const item of catalog.data.solutions) {
  console.log(item.definition.solutionKey, item.compatibilityState);
}
curl -s "https://api.simply360.app/v1/data-collections/DCL1-2345-6789/solutions" \
  -H "Authorization: Bearer $S360_API_KEY"

Each item includes the immutable definition summary, one of READY, NEEDS_SETUP, UNAVAILABLE, INSTALLED, CUSTOMIZED, or ADVANCED_ONLY, plus structured blockers and warnings. An installed item carries teamSolutionInstallationSimplyId. A Blueprint-satisfied item carries exact public Blueprint provenance in preSatisfiedBy and must not be installed again.

Preview and Apply

const preview = await s360.solutions.preview(
  'DCL1-2345-6789',
  'new-record-confirmation',
  {
    schemaVersion: 'simply360.solutions-api/v1',
    configuration: {
      schemaVersion: 'simply360.solution-configuration/v1',
      semanticRoleBindings: {
        recipientEmail: {
          kind: 'FIELD_PATH',
          relationshipDataFieldSimplyIds: [],
          dataFieldSimplyId: 'FLD1-2345-6789',
        },
      },
      choices: {
        sender: { kind: 'PUBLIC_ID', valueSimplyId: 'SEND-2345-6789' },
      },
      activation: { enableNow: false },
    },
    sampleRecordSimplyId: 'RECD-2345-6789',
  },
);

if (preview.data.review.status === 'READY') {
  const applied = await s360.solutions.apply(
    'DCL1-2345-6789',
    'new-record-confirmation',
    {
      schemaVersion: 'simply360.solutions-api/v1',
      configuration: preview.data.normalizedConfiguration,
      reviewFingerprint: preview.data.review.reviewFingerprint,
      idempotencyKey: crypto.randomUUID(),
    },
  );
  console.log(applied.data.result, applied.data.installation.teamSolutionInstallationSimplyId);
}

The server returns exact authorized semantic-role and choice candidates, asset operations, reuse candidates, plain-language behavior keys, bounded sample outputs, blockers, warnings, runtime usage disclosures, and an opaque versioned review fingerprint in the form vN:<64 lowercase hex>. Treat that token as opaque and preserve it exactly. It is a domain-separated keyed MAC, not a public content hash. A sample record is optional, limited to one, and must be readable in the exact Collection.

Apply rechecks the actor, candidates, permissions, dependencies, current assets, and fingerprint under locks. It creates no partial graph. Every apply, apply-update, or detach request must use a newly generated canonical lowercase UUIDv4 as its idempotencyKey; retain that same UUID only while retrying the exact same request. Replaying the same completed request and idempotency key returns REPLAYED. Reusing the key with different input returns IDEMPOTENCY_CONFLICT. A changed preview returns STALE_REVIEW; fetch a new preview and present it for review instead of retrying automatically.

Apply, apply-update, and detach return an immutable, data-minimized mutation receipt with the installation and asset public identities, pinned definition, lifecycle timestamps, and bounded warnings. It intentionally omits configuration and live drift, consumer, and execution state so an exact replay cannot change and the idempotency ledger retains no configuration or preview content. Call s360.solutions.get(receipt.teamSolutionInstallationSimplyId) after a mutation when you need the current full installation representation.

Inspect and Update

const current = await s360.solutions.get('SOLN-2345-6789');
const targetDefinitionVersion = '1.1.0';

const updatePreview = await s360.solutions.previewUpdate('SOLN-2345-6789', {
  schemaVersion: 'simply360.solutions-api/v1',
  configuration: current.data.installation.configuration,
  targetDefinitionVersion,
});

if (updatePreview.data.review.status === 'READY') {
  // Present definitionUpgrade.changes for explicit review when it is present.
  await s360.solutions.applyUpdate('SOLN-2345-6789', {
    schemaVersion: 'simply360.solutions-api/v1',
    configuration: updatePreview.data.normalizedConfiguration,
    reviewFingerprint: updatePreview.data.review.reviewFingerprint,
    idempotencyKey: crypto.randomUUID(),
    targetDefinitionVersion,
  });
}

Inspection returns each asset's public ID, ownership mode, live state, external-consumer flag, and safe recent Automation run time where available. It never includes execution payloads, recipient data, rendered content, or internal errors.

Friendly updates preserve USER_OWNED_AFTER_CREATE properties and reject unsafe overwrites. An ADVANCED_ONLY asset, shared existing asset, unexpected provenance graph, or asset with external consumers must be managed through the owning canonical API/workspace instead.

To upgrade an installation, send the exact registered targetDefinitionVersion in both preview-update and apply-update. When it differs from the installed version, preview returns definitionUpgrade with the current version, target version, and bounded property-change list for explicit review. The fingerprint binds that target and diff. Omitting the target reviews the currently installed version; downgrades are rejected.

Detach

const detached = await s360.solutions.detach('SOLN-2345-6789', {
  schemaVersion: 'simply360.solutions-api/v1',
  idempotencyKey: crypto.randomUUID(),
  reason: 'The team will manage these assets directly.',
});

console.log(detached.data.result); // DETACHED or REPLAYED

Detach is permanent and non-destructive. It retains every canonical asset and the installation history, marks provenance detached, and releases the active Collection/definition slot. It does not delete or disable retained assets.

Structured Errors

Solution failures use the normal API error envelope. details contains schemaVersion, stable code, translation messageKey, optional safe parameters and blockers, and retryable.

Important codes include FORBIDDEN, UNSUPPORTED_PRINCIPAL, ACTIVE_INSTALLATION_EXISTS, STALE_REVIEW, IDEMPOTENCY_CONFLICT, ASSET_COLLISION, DEPENDENCY_UNAVAILABLE, and DEFINITION_VERSION_UNAVAILABLE. Treat structured blockers and remediations as the authority; do not parse human-readable messages or silently fall back to another asset.

MCP and TeamAgent Boundary

MCP and TeamAgent may list, explain, recommend, and preview Solutions and may draft an approval-gated proposal. They have no direct or autonomous enable/apply operation. Approving a proposal invokes the same Cognito Team Admin domain service with enableNow: false; stronger runtime effects keep their separate canonical activation boundaries.

Usage and Sensitive Output

Catalog, preview, apply, update, and detach are authoring operations. They do not send messages, generate PDFs, charge payments, contact signing providers, or record runtime usage. Executing the resulting canonical assets later uses their existing entitlement, allowance, usage-event, invoice, and audit paths.

Sample output has telemetryPolicy: SENSITIVE_NO_CAPTURE. Do not copy rendered sample content into logs, traces, analytics, error reports, or durable client telemetry.

↑