Triggers API
API reference for Pinkfish Triggers
Triggers API
This API enables you to execute Pinkfish workflows that you’ve created and published. With these “trigger” endpoints, you can integrate automated workflows into your applications and systems. You can also trigger one workflow from another workflow - thereby chaining workflows together.
There is no API for other services that you might be looking for, such as retrieving monitor logs, billing data, or workflow CRUD operations.
Key Concepts
-
Workflow: A series of steps that perform a specific task or workflow.
-
Trigger: A mechanism to initiate a workflow via API call. You must set up a trigger in order to call your workflow by API.
-
Run: An instance of a workflow being executed.
Execution Models
Our API supports two execution models:
Asynchronous (Fire and Forget)
When you create a trigger for your workflow, you get two options:
-
API Trigger Endpoint: Use this with the API key in the header (
X-API-KEY
)- Format:
https://triggers.app.pinkfish.ai/ext/triggers/{triggerId}
- Requires API key in request headers
- Best for server-to-server integrations
- Format:
-
Webhook URL: Use this for 3rd party services that can’t set custom headers
- Format:
https://triggers.app.pinkfish.ai/ext/webhook/{apiKey}/triggers/{triggerId}
- API key is embedded in the URL path for authentication
- Best for services like Slack, Discord, Linear, Zoom, and other webhook-based integrations
- Format:
Both options:
- Return immediately with a runId in the response header
- Run the workflow asynchronously in the background
- Don’t return results directly via the API call
- Are best for long-running workflows or when immediate response isn’t required
Synchronous (Wait for Result)
-
When you call a workflow trigger with
x-api-wait: true
, the API waits for up to 60 seconds for completion -
If the workflow completes within this window, the response body contains the results
-
If the workflow takes longer than 60 seconds, the call returns with a timeout and a runId
-
Best for quick workflows where you need immediate results
To view the outcome of a workflow run (especially for async calls or timeouts), you have several options:
-
Check the effects of the workflow (e.g., a created Google Doc or message to Slack). This is entirely up to you to devise.
-
Load the workflow in the platform UI (you will see results from the last run). Warning: if you have edited your workflow since your last publish, you won’t see results here.
-
Use the Runs Monitor in the platform to view execution status and results. This is the most reliable and simple method.
Authentication
All API endpoints are authenticated using API keys. Include your API key in the X-API-KEY
header of each request:
You can generate API keys in two ways:
-
In the Library section of the platform interface.
-
While setting up a trigger for a workflow.
Triggering Workflows
Workflows are executed by calling their associated triggers. Each trigger has a unique endpoint and may accept parameters either as query parameters (for GET requests), as form-encoded data, or as a json payload. Set up your trigger(s) in the Workflow editor (requires first publishing a version of your workflow)
Example Requests
Asynchronous Request (Form-encoded)
Synchronous Request (JSON)
Example Responses
Asynchronous Response
The response body will be null. You can find your runId in the header as X-Pf-Run-Id
.
Synchronous Response (Successful)
If the workflow completes within 60 seconds, you’ll receive the results in the response body:
Synchronous Response (Timeout)
If the workflow doesn’t complete within 60 seconds:
Webhook Triggers
Webhook triggers provide an alternative way to execute workflows when working with third-party services that cannot set custom headers (like Slack, Discord, Linear, Zoom, etc.).
Webhook URL Format
Key Differences from API Triggers
Feature | API Trigger | Webhook Trigger |
---|---|---|
Authentication | API key in X-API-KEY header | API key embedded in URL path |
URL Format | /ext/triggers/{triggerId} | /ext/webhook/{apiKey}/triggers/{triggerId} |
Use Case | Server-to-server integrations | Third-party services with webhook support |
Security | More secure (key in headers) | Less secure (key visible in URL) |
Example Webhook Request
Security Considerations
Since the API key is embedded in the webhook URL:
- Treat webhook URLs as sensitive credentials
- Only share with trusted third-party services
- Consider rotating API keys periodically
- Monitor webhook usage in the Runs Monitor
Common Webhook Integrations
- Slack: Use in Slack workflows or slash commands
- Discord: Set up bot commands or server events
- Linear: Trigger workflows on issue updates
- Zoom: Execute workflows from Zoom apps
- GitHub: Run workflows on repository events
- Stripe: Process payment events
Getting Started
To begin using the AI Workflow API, you’ll need to:
-
Create and publish a workflow using our platform.
-
Set up a trigger for your workflow.
-
Generate an API key from either the Library section or during trigger setup.
-
Choose your execution model (sync or async) based on your workflow’s expected runtime and your application’s needs.
-
Use the provided trigger endpoint to execute your workflow, including your API key and preferred wait setting in the request headers.