Build your first workflow connector

Create a workflow connector with the Stacksync CLI, build its modules with the CDK, test it in your workspace and deploy it.

In this guide you create a workflow connector, build a module, test it in the workflow builder while it runs on your machine, and deploy it. The example connects to a CRM called Acme CRM. Replace it with the system you want to connect.

A workflow connector connects Stacksync to one system, such as an API, a database or an internal service. It contains modules: each module is one step a workflow can run, such as Create records. You build the connector with the Workflow Connector Development Kit (CDK), a Python library.

Prerequisites

The Stacksync CLI installed and logged in. See the Quickstart.
Python 3.10 or later.
The API documentation of the system you are connecting, and an account to test with.

Build with an AI coding assistant

The generated project includes AGENTS.md, CLAUDE.md and a guide/ folder, so an AI coding assistant such as Claude Code, Codex or Cursor follows the same rules that Stacksync checks at deployment. Paste this prompt into your assistant, or follow the steps below yourself.

Prompt for an AI coding assistant

Build a Stacksync workflow connector with the Stacksync CLI and the Stacksync CDK.

Requirements:
- Application: <application name>. Ask me if it is missing.
- Operations: <the operations the connector must support>. If I don't know, propose them from the API documentation.
- API documentation: <official documentation URL, optional>. Find it if it is missing.
- Other requirements: <optional>

Process:
1. Read these pages fully before you start. They are the reference for the CLI and the CDK:
   https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/build-your-first-workflow-connector.md
   https://docs.stacksync.com/developers/stacksync-cdk/workflow-connector-development-kit.md
   https://docs.stacksync.com/developers/stacksync-cdk/modules.md
   https://docs.stacksync.com/developers/stacksync-cdk/context.md
   https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/deploy-a-workflow-connector.md
   https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/cli-command-reference.md
2. Research the application's API: authentication, base URL, every standard object, how custom objects and fields are listed, endpoints, pagination and rate limits.
3. Run `stacksync --version`. If the command is missing, install the CLI:
   curl -fsSL https://cli.stacksync.com/install.sh | sh
4. Run `stacksync login --check`. If it prints "Not logged in", ask me to run `stacksync login` (it opens a browser), or to give you an API key for `stacksync login --api-key <key> --workspace <id>`.
5. Create the project and enter it:
   stacksync workflow-connector create "<Application Name>"
   cd workflows-app-<application-name>
6. Read AGENTS.md and every file in guide/ before you change anything. Follow them exactly.
7. Fill in stacksync.yml: app_name, app_description, app_icon_svg_url (a stable https link to an SVG logo) and connection_app_type. Keep generic_api_credentials unless I say Stacksync set up a dedicated connection type for this app.
8. Build one module per operation (create_records, update_records, get_records, ...), with the object chosen in a dropdown. Never one module per object. Add modules with:
   stacksync workflow-module create "<Module Name>"
   Remove the sample module if it is not used: stacksync workflow-module delete create_records
9. Write the connector's context.md and each module's context.md completely. No TODO may remain.
10. Run the connector standard check and fix every problem it reports:
    .venv/bin/python -m stacksync_cdk.connector_checks
    (The .venv folder exists after the first `stacksync workflow-connector run`.)
11. Start the connector: stacksync workflow-connector run
    Tell me to create a connection of the type in connection_app_type in Stacksync (Connections > Create connection), then to refresh the workflow builder, add an Action step and pick the connector. Tell me how to test each module.
12. Stop after local testing. Deploy only when I ask: stacksync workflow-connector deploy, then report the deployment id and check it with stacksync workflow-connector deploy-status <id>.

Ask only for what the API documentation and the project guides cannot answer. Never invent endpoints, fields, credentials, connection types or workspace values. Never print or commit credentials.

Build, test and deploy

Create the connector

stacksync workflow-connector create "Acme CRM"
cd workflows-app-acme-crm

The project has everything a connector needs, plus a working sample module, create_records:

workflows-app-acme-crm/
  stacksync.yml        connector settings
  context.md           what the connector is, for Stacksync's AI
  requirements.txt     the Stacksync CDK and your dependencies
  main.py              entry point (leave as is)
  AGENTS.md            rules for AI coding assistants (CLAUDE.md points to it)
  README.md
  guide/               how to build each part
  utils/               helpers shared by modules
  modules/
    create_records/v1/ schema.py, content.py, execute.py, config.py, context.md

Each file is explained in Workflow Connector Development Kit.

Fill in the connector settings

Open stacksync.yml. create already set the workspace, app_type and the names. Fill in the rest:

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"

region is where run registers the temporary connector: usnv (United States) or besg (Europe). Use your workspace's default region. A deployed connector is available in every region.
app_icon_svg_url must be a stable https:// link to an SVG logo.
connection_app_type decides what users connect with. Keep generic_api_credentials to start: the user pastes one value, such as an API key.
app_type is the connector's permanent id: lowercase words joined by underscores, at most 24 characters, unique across Stacksync. See Connections and credentials.

Every field is described in stacksync.yml.

Plan the modules

Build one module per operation, and let the user pick the object inside it:

Do	Don't
`create_records` with an object dropdown: Contact, Company, Deal	`create_contact`, `create_company`, `create_deal`

Most connectors need some of create_records, update_records, upsert_records, delete_records, get_records and list_records, plus a module for each action that is not record work, such as send_email. Stacksync reviewers reject connectors with one module per object.

Add a module:

stacksync workflow-module create "Get Records"

Remove the sample if you don't need it:

stacksync workflow-module delete create_records

Build the module

A module is a folder of small Python functions. The CDK turns them into the endpoints Stacksync calls.

File	Function	What it does
`schema.py`	`schema(request) -> SchemaResponse`	Returns the form the user fills in.
`content.py`	`content(request) -> ContentResponse`	Returns the options of dropdowns, such as the list of objects.
`execute.py`	`execute(request) -> ExecuteResponse`	Runs the step: calls your API and returns the result.
`config.py`	`CONFIG = ModuleConfig(...)`	Name, description and settings of the module.
`context.md`		Explains the module to Stacksync's AI.

A minimal execute.py that reads an API key from a generic_api_credentials connection:

import requests

from stacksync_cdk import ExecuteResponse, ManagedError, Request

BASE_URL = "https://api.acme-crm.example.com/v1"


def execute(request: Request) -> ExecuteResponse:
    selected_object = request.data.get("select_object")
    records = request.data.get(f"{selected_object}s") or []
    if not records:
        raise ManagedError.validation_error(f"At least one {selected_object} is required.")

    api_key = request.credentials.get("api_credentials")
    if not api_key:
        raise ManagedError.unauthorized(
            'This connection has no API key. Its value should look like {"api_credentials": "your-api-key"}.'
        )

    created = []
    for record in records:
        response = requests.post(
            f"{BASE_URL}/{selected_object}s",
            json=record,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        if response.status_code == 401:
            raise ManagedError.unauthorized("Acme CRM rejected the API key. Update the connection.")
        response.raise_for_status()
        created.append(response.json())

    return ExecuteResponse(created, metadata={"affected_records": len(created)})

The form, dropdowns, credentials, errors and field types are covered in Build modules.

Write the context

Stacksync's AI reads context.md to choose your module, fill its form and run it. Fill in the connector's context.md and each module's context.md, section by section. Stacksync refuses to deploy while a required section is missing, empty or still contains TODO. See Context and the /context endpoint.

Check the connector

Check the connector against the connector standard, the same check Stacksync runs when you deploy:

.venv/bin/python -m stacksync_cdk.connector_checks

.venv is created by the first stacksync workflow-connector run. If you manage your own virtual environment, activate it and run python -m stacksync_cdk.connector_checks. Fix every problem until it reports none.

Run and test

stacksync workflow-connector run

Stacksync CDK 1.1.1 (tracking @v1)
Starting application on http://127.0.0.1:2323 (Ctrl+C to stop)
Temporary connector registered with Stacksync.

The connector now runs on your machine and is available in your workspace while run keeps running. To test it:

In Stacksync, create a connection of the type in connection_app_type under Connections → Create connection. For generic_api_credentials, paste your API key.
Create or open a workflow and refresh the workflow builder.
Add an Action step and choose your connector and module.
Select the connection, fill in the form and run the step.

Each request is handled by your local code. Saved changes reload automatically. If a step fails, fix the code and send the same request again without rerunning the workflow:

stacksync workflow-connector replay last

Press Ctrl+C to stop. The temporary connector is removed from the workspace.

Deploy

When every module works, deploy the connector:

stacksync workflow-connector deploy

Deployment 3f2a9c0e8b7d4e1fa6c5b4d3e2f1a0b9 submitted for review.
It is built and deployed once a Stacksync reviewer approves it. You will get an email when it ends.

A Stacksync reviewer checks the connector before it is built. Follow it with:

stacksync workflow-connector deploy-status 3f2a9c0e8b7d4e1fa6c5b4d3e2f1a0b9

When the status is Live, the connector is available in the workflow builder of every Stacksync workspace, without run. See Deploy a workflow connector for the review, the statuses and how to ship updates.

Next steps

Build modules Context and the /context endpoint Deploy a workflow connector CLI command reference

PrerequisitesCopy Anchor Link

Build with an AI coding assistantCopy Anchor Link

Build, test and deployCopy Anchor Link

Create the connectorCopy Anchor Link

Fill in the connector settingsCopy Anchor Link

Plan the modulesCopy Anchor Link

Build the moduleCopy Anchor Link

Write the contextCopy Anchor Link

Check the connectorCopy Anchor Link

Run and testCopy Anchor Link

DeployCopy Anchor Link

Next stepsCopy Anchor Link

On this page