How to Connect Any Two Apps with Stacker PIPEs - Manual Endpoint Guide

What You'll Learn

How to connect any two self-hosted applications with a Stacker PIPE using manual endpoint specification. This approach works even when apps aren't running - no endpoint discovery required.

• Create pipes with explicit source and target endpoints
• Map data fields between different APIs
• Activate, trigger, and monitor pipe execution
• Troubleshoot common pipe errors

Quick Answer

stacker pipe create <source> <target> \
  --source-endpoint "METHOD /path" \
  --target-endpoint "METHOD /path" \
  --source-fields field1,field2 \
  --target-fields field1,field2 \
  --name "my-pipe"

Why Manual Endpoints?

Stacker's endpoint discovery scans running containers for OpenAPI specs, HTML forms, and REST API patterns. But not all apps expose standard paths. Apps like Directus (at /items/*) or Chatwoot (at /api/v1/*) use non-standard routes that the probe doesn't find.

Manual endpoint specification bypasses discovery entirely. You tell the pipe exactly where to fetch and where to deliver - no scanning, no guessing, no running containers required.

Step 1: Create the Pipe

Define the source endpoint (where data comes from) and target endpoint (where data goes):

stacker pipe create directus chatwoot \
  --source-endpoint "POST /items" \
  --target-endpoint "POST /api/v1/conversations" \
  --source-fields "name,email,message" \
  --target-fields "content" \
  --name "directus-chatwoot"

This creates a pipe template that maps name, email, and message from Directus to content in Chatwoot.

Step 2: Activate the Pipe

stacker pipe list                    # get the pipe ID
stacker pipe activate <pipe-id>      # start listening for data

Step 3: Trigger and Test

stacker pipe trigger <pipe-id> --data '{"name":"Test","email":"test@example.com","message":"Hello!"}'
stacker pipe history <pipe-id>       # view execution log

Supported Endpoint Formats

• Method + path: POST /api/v1/items - specifies HTTP method and path
• Bare path: /api/v1/items - defaults to GET

How Field Mapping Works

When you specify --source-fields and --target-fields, the pipe maps fields by position. The first source field maps to the first target field, and so on.

# Source: name, email, message
# Target: content
# Result: all three source fields are combined into the "content" target field

For more complex transformations, use JSONPath expressions with the source_url activation method.

Example: Directus to Chatwoot

When a new item is created in Directus, send a message to Chatwoot:

# Create the pipe
stacker pipe create directus chatwoot \
  --source-endpoint "POST /items" \
  --target-endpoint "POST /api/v1/conversations" \
  --source-fields "name,email,message" \
  --target-fields "content" \
  --name "directus-chatwoot"

# Activate
stacker pipe activate <pipe-id>

# Test with sample data
stacker pipe trigger <pipe-id> --data '{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "message": "I need help with my order"
}'

# Check execution log
stacker pipe history <pipe-id>

Benefits of Manual Endpoints

• No discovery required - works even when apps aren't running
• No agent dependency - bypasses endpoint discovery limitations
• Immediate - create pipes in seconds
• Flexible - works with any HTTP API endpoint
• Portable - same pipe works across environments

Troubleshooting

"Not a terminal" error

Use the --name flag to skip interactive prompts. The pipe create command defaults to an interactive name prompt that fails in scripts.

"Authentication token expired" error

Run stacker login to refresh your session before running pipe commands.

Fields not matching

Use --source-fields and --target-fields to explicitly specify field names. Position-based mapping requires the same number of fields on both sides.

Frequently Asked Questions

Can I create pipes without running containers?

Yes. Manual endpoint specification doesn't require the apps to be running. The pipe is a template that activates when the apps are available.

What HTTP methods are supported?

Any standard HTTP method: GET, POST, PUT, PATCH, DELETE. Specify it in the endpoint string (e.g., POST /api/v1/items).

How do I map fields with different names?

Use --source-fields and --target-fields to map by position. For JSONPath-based mapping, use the source_url activation method.

Can I use this with APIs that require authentication?

Yes. Use --target-header "Authorization: Bearer <TOKEN>" when activating or triggering the pipe.

Key Takeaways

• Manual endpoints work without running containers or endpoint discovery
• Use --name flag to avoid interactive prompts in scripts
• Field mapping is position-based - match source fields to target fields
• Works with any HTTP API, any method, any authentication scheme
• Pipes are reusable - activate once, trigger as needed