Workflow Connector Development Kit

The Workflow Connector Development Kit (CDK) is the Python library you build workflow connectors with. You write each module as a few plain functions. The CDK finds them on disk and serves them as the endpoints Stacksync calls when someone builds or runs a workflow.

The Stacksync CLI creates the project, runs it on your machine and deploys it. New to both? Start with Build your first workflow connector.

ConceptsCopy Anchor Link

InstallCopy Anchor Link

The CDK is installed from GitHub through the project's requirements.txt. The CLI installs it for you when you run the connector.

git+https://github.com/stacksyncdata/stacksync-workflows-cdk.git@v1#subdirectory=lib

• Package: stacksync-cdk. Import: stacksync_cdk. It is not published on PyPI.
• Python 3.10 or later on your machine. Deployed connectors run on Python 3.11.
• Dependencies: Flask 3.1.3 or later, Pydantic 2 and PyYAML 6.

Project layoutCopy Anchor Link

stacksync workflow-connector create "Acme CRM" creates:

workflows-app-acme-crm/
├── stacksync.yml            connector settings
├── context.md               the connector's context for Stacksync's AI (required)
├── main.py                  entry point: app = create_app(...)
├── requirements.txt         the CDK and your dependencies
├── AGENTS.md                rules for AI coding assistants
├── CLAUDE.md                points Claude Code to AGENTS.md
├── README.md
├── LICENSE
├── .gitignore
├── guide/                   architecture, building, schema, content, execute and context guides
├── utils/                   code shared by modules, such as an API client
└── modules/
    └── create_records/      a sample module
        └── v1/
            ├── schema.py    the input form
            ├── content.py   dropdown options
            ├── execute.py   the action
            ├── config.py    module name, description and settings
            └── context.md   the module's context (required)

Rules for the project folder:

• Modules are found on disk. Add a folder modules/<module>/v<N>/ and the module exists. Nothing is listed in stacksync.yml.
• Module folder names are lowercase words joined by underscores, such as create_records. Version folders are v followed by digits, such as v1.
• main.py must keep defining app. Stacksync serves that object once deployed.
• The connector root may contain only main.py, stacksync.yml, requirements.txt, context.md, README.md, LICENSE, AGENTS.md, CLAUDE.md, modules/, utils/, tests/, guide/, pyproject.toml, uv.lock, requirements-dev.txt, conftest.py, pytest.ini, and hidden files. A Dockerfile or gunicorn_config.py is allowed but replaced by Stacksync's own. Anything else blocks the deployment. Keep scripts and notes outside the connector folder.

stacksync.ymlCopy Anchor Link

deployment_settings:
  workspace: "1234"
  region: "usnv"

app_settings:
  app_type: "acme_crm"
  app_name: "Acme CRM"
  app_type_display: "Acme CRM"
  app_icon_svg_url: "https://www.example.com/acme-crm-logo.svg"
  app_description: "Create, update and look up Acme CRM records."
  connection_app_type: "generic_api_credentials"

Never put credentials in stacksync.yml or in code. Users store them in a Stacksync connection.

Module settings: config.pyCopy Anchor Link

Each module version has a config.py that exports CONFIG. Every field has a default, so set only what differs:

from stacksync_cdk import ModuleConfig

CONFIG = ModuleConfig(
    module_name="Create Records",
    module_description="Create one or more records of any object type.",
)

Module versionsCopy Anchor Link

The module id is <app_type>-<module>-<N>, for example acme_crm-create_records-1.

• Start every module at v1.
• Edit v1 in place for changes that keep existing workflows working: a new optional field, a bug fix, a clearer label.
• Add modules/<module>/v2/ next to v1 for a breaking change to inputs or behavior. Both versions are served, so workflows built on v1 keep working and new workflows use v2.
• Never delete a deployed version: Stacksync refuses the deployment.
• The name, description, icon and settings of a version are recorded the first time it is deployed. Changes to them later don't appear. Ship such a change in a new version.

CDK versionsCopy Anchor Link

The CDK follows semantic versioning. The @ref in requirements.txt decides which release you get:

Change it with stacksync workflow-connector cdk <ref>. run reinstalls the moving references (@v1, @v2, @prod) each time it starts and prints the installed version. Deployed connectors install the reference in requirements.txt when they are built. The current release is 1.1.1. Deployments need 1.1.0 or later.

The libraryCopy Anchor Link

Everything you need is imported from stacksync_cdk:

How to use them is covered in Build modules.

create_app refuses to start without app_type. It still starts when the connector breaks the connector standard, and logs each problem as Must fix before deploying: …. Logging is set to INFO unless you configure it. Use Python's logging module in handlers, and never log credentials.

EndpointsCopy Anchor Link

The CDK serves these endpoints. Stacksync calls them, so you never write them yourself. You can call them on the local server that run starts, which helps with testing.

Every answer is JSON with a data key. Errors answer {"error": "<message>"} with the HTTP status of the error. The request and response bodies of each endpoint are described in Build modules.

curl http://127.0.0.1:2323/app-config
curl http://127.0.0.1:2323/create_records/v1/context

LimitsCopy Anchor Link

Next stepsCopy Anchor Link