Coming soon · Contract draft

Integrations & Operations

Planned

A unified administration contract for extension catalogs, installations, health checks, dry runs, sync operations, cancellation, and results.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Extension lifecycle service and normalized operation service

Contract posture

P1 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Platform + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 0–2 · Platform substrate

Contract dependencies

• Principal × scope grantability matrix
• Versioned interface catalog
• Transactional audit and event contracts

What this unlocks

Inspect connection health

Read a stable domain model for integrations & operations without depending on GUI routes or database shapes.

Preview synchronization safely

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Track asynchronous work

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Integrations & Operations exposes a bounded lifecycle with explicit commands and named authority at every transition.

installeddisabledenableddegradedrevoked

From	To	Command	Authority
installed	enabled	Enable connection	Extension lifecycle service
enabled	degraded	Record unhealthy state	Extension lifecycle service
degraded	enabled	Recover connection	Extension lifecycle service
enabled	revoked	Revoke connection	Extension lifecycle service

Lifecycle invariants

• Credential material never leaves the secret boundary.
• Dry run and apply are distinct operations.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

• Installation and enablement state
• Normalized operation lifecycle
• Credential-health status without secret material

Explicitly not building

• Raw worker queues or leases
• Secret or token retrieval
• Hidden apply after a dry run

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Installation, health, sync-run, dry-run, cancellation, and result resources

A normalized lifecycle lets every provider expose the same operational contract.

keep

Generic Operation resources for asynchronous work

Customers need stable status and results without seeing Trigger.dev queues or worker leases.

remove

Raw credentials, tokens, worker queues, and retry internals

Those are implementation and security details, not customer domain objects.

Interface plan

REST API

Planned

Versioned integrations & operations resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable Integration reads with mutations delegated to the same canonical domain service.

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and confirmed apply tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense integration lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Timely / Runn / Jira / Calendar plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

Capability	REST	GraphQL	MCP	Webhook	Canonical owner
Primary read	GET /integrations	integration(id: ID!): Integration	get_integrations_operations	—	Extension lifecycle service and normalized operation service
Primary command	POST /integrations	draftIntegrationChange(input: DraftIntegrationChangeInput!): IntegrationChangeProposal!	draft_integrations_operations_change	integration.created	Extension lifecycle service and normalized operation service

Proposed scopes

Proposed scopes are not grantable yet.

integrations:readplanned scope

Read governed integrations & operations resources.

integrations:writeplanned scope

Create and edit bounded integrations & operations fields.

integrations:operateplanned scope

Run explicit integrations & operations lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Extension lifecycle service and normalized operation service; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Safe writes

Mutations use explicit confirmation where required, optimistic concurrency, idempotency, and durable actor attribution.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned

GET/api/v1/integrations

List integrations & operations

Return an authorized, paginated collection with stable filters and provenance.

integrations:read

POST/api/v1/integrationsconfirmation

Create Integration

Create one canonical resource with idempotency and actor attribution.

integrations:write

GET/api/v1/integrations/{id}

Retrieve Integration

Return canonical detail, lifecycle state, permissions, and allowed actions.

integrations:read

PATCH/api/v1/integrations/{id}confirmation

Update Integration

Update bounded editable fields using optimistic versioning.

integrations:write

POST/api/v1/integrations/{id}/run-dry-runconfirmation

run dry run Integration

Run one explicit domain command after validation and authorization.

integrations:operate

GET/api/v1/integrations/{id}/health

Get integration health

Return sanitized credential, mapping, and recent-run health.

integrations:read

Execution: Synchronous

GET/api/v1/integrations/{id}/sync-runs

List sync runs

List dry-run and applied synchronization operations.

integrations:read

Execution: Synchronous

run dry run a Integration

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/integrations/integration_123/run-dry-run \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: integrations-operations-run-dry-run-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "integration_123",
    "status": "validated",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

Integration

IntegrationConnection

IntegrationChangeProposal

Operation

Queries

integration(id: ID!): Integration

integrationList(filter: IntegrationFilter, pagination: PaginationInput): IntegrationConnection!

Mutations

draftIntegrationChange(input: DraftIntegrationChangeInput!): IntegrationChangeProposal!

applyIntegrationChange(input: ApplyIntegrationChangeInput!): IntegrationPayload!

Planned GraphQL query

query IntegrationDetail($id: ID!) {
  integration(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Integrations & Operations

get_integrations_operations

Planned

Read the authorized integrations & operations state, provenance, and allowed actions.

Scope: integrations:read
Input: Resource id or a bounded filter.
Output: Canonical detail with source provenance and allowed actions.
Write boundary: Read only.

Draft Integrations & Operations change

draft_integrations_operations_change

Planned

Build a reviewable proposal from explicit user intent and DigitalStack evidence.

Scope: integrations:write
Input: Target, requested outcome, expected version, and optional evidence references.
Output: A persisted proposal, validation results, and conflicts.
Write boundary: Creates a proposal; it does not mutate canonical state.

Apply Integrations & Operations change

apply_integrations_operations_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: integrations:operate
Input: Proposal id, expected version, idempotency key, and explicit confirmation.
Output: Updated canonical resource and audit reference.
Write boundary: Confirmation, optimistic versioning, and idempotency required.

Planned agent workflow

User: Review the proposed integrations & operations change and help me apply it.

1. Call get_integrations_operations to inspect current state, provenance, and allowed actions.
2. Call draft_integrations_operations_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. After explicit confirmation, call apply_integrations_operations_change with the proposal version.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

integration.createdplanned event

A canonical Integration was created.

payload: integration_id, status, created_at

integration.updatedplanned event

Governed Integration fields changed.

payload: integration_id, changed_fields, version, occurred_at

integration.validatedplanned event

The run dry run command completed.

payload: integration_id, prior_status, status, occurred_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "integration.validated",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "integration",
    "id": "integration_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "integration_id": "integration_123",
    "prior_status": "draft",
    "status": "validated"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded integrations & operations proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

Timely / Runn / Jira / Calendar

Synchronization provider

Install and operate providers through a common lifecycle contract.

Authority: Each provider declares direction, mappings, conflict policy, and supported commands.

Open contract decisions

Resolve before implementation approval

• Which provider operations can be safely cancelled after execution begins?

Proof obligations

Must remain true	Failure indicator
Extension lifecycle service and normalized operation service remains the singular canonical owner.	An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.	An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.	A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.	Provider data silently becomes canonical or conflicts are resolved without policy.