Triggers API

​

Triggers API

This API enables you to execute Pinkfish automations 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 automation from another automation - thereby chaining automations together.

There is no API for other services that you might be looking for, such as retrieving monitor logs, billing data, or automation CRUD operations.

​

Key Concepts

• Automation: A series of steps that perform a specific task or workflow.

• Trigger: A mechanism to initiate an automation via API call. You must set up a trigger in order to call your automation by API.

• Run: An instance of an automation being executed.

​

Execution Models

Our API supports two execution models:

​

Asynchronous (Fire and Forget)

When you create a trigger for your automation, you get two options:

1. 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

2. 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

Both options:

• Return immediately with a runId in the response header
• Run the automation asynchronously in the background
• Don’t return results directly via the API call
• Are best for long-running automations or when immediate response isn’t required

​

Synchronous (Wait for Result)

• When you call an automation trigger with x-api-wait: true, the API waits for up to 60 seconds for completion

• If the automation completes within this window, the response body contains the results

• If the automation takes longer than 60 seconds, the call returns with a timeout and a runId

• Best for quick automations where you need immediate results

To view the outcome of an automation run (especially for async calls or timeouts), you have several options:

1. Check the effects of the automation (e.g., a created Google Doc or message to Slack). This is entirely up to you to devise.

2. Load the automation in the platform UI (you will see results from the last run). Warning: if you have edited your automation since your last publish, you won’t see results here.

3. 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:

X-API-KEY: YOUR_API_KEY_HERE

You can generate API keys in two ways:

1. In the Library section of the platform interface.

2. While setting up a trigger for an automation.

​

Triggering Automations

Automations 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 Automation editor (requires first publishing a version of your automation)

​

Example Requests

​

Asynchronous Request (Form-encoded)

curl --location 'https://triggers.app.pinkfish.ai/ext/triggers/YOUR_AUTOMATION_ID' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'x-api-wait: false' \
--data-urlencode 'Hello=World'

​

Synchronous Request (JSON)

curl --location 'https://triggers.app.pinkfish.ai/ext/triggers/YOUR_AUTOMATION_ID' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'x-api-wait: true' \
--data '{
    "user_request": "what is the capital of France"
}'

​

Example Responses

​

Asynchronous Response

The response body will be null. You can find your runId in the header as X-Pf-Run-Id.

Response Headers
Date: Wed, 18 Sep 2024 02:12:39 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
x-amzn-RequestId: eea7315a-f8c2-4c55-88df-50f8332bf25e
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, Authorization
X-Pf-Automation-Id: crkbpb5b9nas7163a4kg
x-amz-apigw-id: eR2LpEkBPHcEK9w=
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
X-Amzn-Trace-Id: Root=1-66ea3717-03397efa60d2632525a8fe5f
X-Pf-Run-Id: 1726625559774364090
Response Body
null

​

Synchronous Response (Successful)

If the automation completes within 60 seconds, you’ll receive the results in the response body:

{
    "automationId": "csrtvshm36rc711dhoqg",
    "automationVersion": 1,
    "automationName": "Hello Triggers",
    "id": "1731715310692281375",
    "type": "TRIGGER",
    "stepMap": {
        "1": 2,
        "2": 2
    },
    "inputs": "",
    "triggerId": "csru0bg3tgfs71020ssg",
    "results": [
        {
            "stepIndex": 1,
            "stepVersion": 2,
            "result": {
                "stepIndex": 1,
                "resultType": "markdown",
                "result": "# Hello from step 1! 👋"
            },
            "exitCode": 0,
            "duration": 790
        },
        {
            "stepIndex": 2,
            "stepVersion": 2,
            "result": {
                "stepIndex": 2,
                "resultType": "plaintext",
                "result": "Hello from step 2!"
            },
            "exitCode": 0,
            "duration": 707
        }
    ],
    "started": "2024-11-16T00:01:50Z",
    "startedBy": "588233679836"
}

​

Synchronous Response (Timeout)

If the automation doesn’t complete within 60 seconds:

Response Headers
[same as async response]

Response Body
{
    "status": "timeout",
    "message": "Automation execution exceeded 60 second timeout. Use runId to check results in Run Monitor."
}

​

Webhook Triggers

Webhook triggers provide an alternative way to execute automations when working with third-party services that cannot set custom headers (like Slack, Discord, Linear, Zoom, etc.).

​

Webhook URL Format

https://triggers.app.pinkfish.ai/ext/webhook/{apiKey}/triggers/{triggerId}

​

Key Differences from API Triggers

​

Example Webhook Request

POST https://triggers.app.pinkfish.ai/ext/webhook/L2wOL4e7yr6G3Us5LKqHa1BLuhMIW5iR1vAqwFga/triggers/d1a49cl8hlvc714q38e0
Content-Type: application/json

{
    "event": "issue_created",
    "issue_id": "12345",
    "title": "New feature 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 automations on issue updates
• Zoom: Execute automations from Zoom apps
• GitHub: Run automations on repository events
• Stripe: Process payment events

​

Getting Started

To begin using the AI Automation API, you’ll need to:

1. Create and publish an automation using our platform.

2. Set up a trigger for your automation.

3. Generate an API key from either the Library section or during trigger setup.

4. Choose your execution model (sync or async) based on your automation’s expected runtime and your application’s needs.

5. Use the provided trigger endpoint to execute your automation, including your API key and preferred wait setting in the request headers.