API Usage Examples

All examples below demonstrate how to trigger flows using a Bearer Token and a JSON payload.

Request Details

• Method: POST
• Authorization: Bearer Token (workspace-level)
• Content-Type: application/json

Sample Payload

Replace:

• {workspace_id} with your workspace ID
• {trigger_id} with your trigger ID
• {environment} with DEV / UAT / PROD
• workspace_api_key with your workspace token

cURL - Single Endpoint

curl -X POST "https://app.phinite.ai/api/v1/ai/trigger/{workspace_id}/{trigger_id}/{environment}" \
  -H "Authorization: Bearer workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "start the task",
    "user_variables": {
      "key1": "value1",
      "key2": "value2"
    }
  }'

cURL - Background Task Start

curl -X POST "https://app.phinite.ai/api/v1/ai/trigger/start/{workspace_id}/{trigger_id}/{environment}" \
  -H "Authorization: Bearer workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "start the task",
    "user_variables": {
      "key1": "value1",
      "key2": "value2"
    }
  }'

cURL - Background Task Status

curl -X GET "https://app.phinite.ai/api/v1/ai/trigger/status/{workspace_id}/{workflow_id}" \
  -H "Authorization: Bearer workspace_api_key"

Python - Single Endpoint

import requests
import json

url = "https://app.phinite.ai/api/v1/ai/trigger/{workspace_id}/{trigger_id}/{environment}"

payload = json.dumps({
  "message": "start the task",
  "user_variables": {
    "key1": "value1",
    "key2": "value2"
  }
})

headers = {
  'Authorization': 'Bearer workspace_api_key',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Python - Background Task

import requests
import json
import time

# Start the flow
url_start = "https://app.phinite.ai/api/v1/ai/trigger/start/{workspace_id}/{trigger_id}/{environment}"

payload = json.dumps({
  "message": "start the task",
  "user_variables": {
    "key1": "value1",
    "key2": "value2"
  }
})

headers = {
  'Authorization': 'Bearer workspace_api_key',
  'Content-Type': 'application/json'
}

response = requests.post(url_start, headers=headers, data=payload)
result = response.json()
workflow_id = result['workflow_id']

# Poll for status
url_status = f"https://app.phinite.ai/api/v1/ai/trigger/status/{{workspace_id}}/{workflow_id}"

while True:
    status_response = requests.get(url_status, headers=headers)
    status_data = status_response.json()

    if status_data['status'] in ['completed', 'failed']:
        print(status_data)
        break

    print(f"Status: {status_data['status']}, Logs: {len(status_data['logs'])}")
    time.sleep(5)  # Poll every 5 seconds

JavaScript - Single Endpoint

const axios = require('axios');

let data = JSON.stringify({
  "message": "start the task",
  "user_variables": {
    "key1": "value1",
    "key2": "value2"
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://app.phinite.ai/api/v1/ai/trigger/{workspace_id}/{trigger_id}/{environment}',
  headers: {
    'Authorization': 'Bearer workspace_api_key',
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

JavaScript - Background Task

const axios = require('axios');

async function runBackgroundTask() {
  // Start the flow
  const startData = JSON.stringify({
    "message": "start the task",
    "user_variables": {
      "key1": "value1",
      "key2": "value2"
    }
  });

  const startConfig = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://app.phinite.ai/api/v1/ai/trigger/start/{workspace_id}/{trigger_id}/{environment}',
    headers: {
      'Authorization': 'Bearer workspace_api_key',
      'Content-Type': 'application/json'
    },
    data: startData
  };

  const startResponse = await axios.request(startConfig);
  const workflowId = startResponse.data.workflow_id;
  console.log('Workflow started:', workflowId);

  // Poll for status
  const statusUrl = `https://app.phinite.ai/api/v1/ai/trigger/status/{workspace_id}/${workflowId}`;

  while (true) {
    const statusResponse = await axios.get(statusUrl, {
      headers: { 'Authorization': 'Bearer workspace_api_key' }
    });

    const status = statusResponse.data.status;
    console.log(`Status: ${status}, Logs: ${statusResponse.data.logs.length}`);

    if (status === 'completed' || status === 'failed') {
      console.log('Final result:', statusResponse.data);
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
  }
}

runBackgroundTask();

Go - Single Endpoint

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {
  url := "https://app.phinite.ai/api/v1/ai/trigger/{workspace_id}/{trigger_id}/{environment}"
  method := "POST"

  payload := strings.NewReader(`{
    "message": "start the task",
    "user_variables": {
      "key1": "value1",
      "key2": "value2"
    }
  }`)

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Authorization", "Bearer workspace_api_key")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Go - Background Task

package main

import (
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "strings"
  "time"
)

type StartResponse struct {
  WorkflowID string `json:"workflow_id"`
  Status     string `json:"status"`
}

type StatusResponse struct {
  WorkflowID string        `json:"workflow_id"`
  Status     string        `json:"status"`
  Logs       []interface{} `json:"logs"`
  Response   interface{}   `json:"response"`
}

func main() {
  // Start the flow
  startURL := "https://app.phinite.ai/api/v1/ai/trigger/start/{workspace_id}/{trigger_id}/{environment}"

  payload := strings.NewReader(`{
    "message": "start the task",
    "user_variables": {
      "key1": "value1",
      "key2": "value2"
    }
  }`)

  client := &http.Client{}
  req, _ := http.NewRequest("POST", startURL, payload)
  req.Header.Add("Authorization", "Bearer workspace_api_key")
  req.Header.Add("Content-Type", "application/json")

  res, _ := client.Do(req)
  defer res.Body.Close()

  body, _ := io.ReadAll(res.Body)

  var startResp StartResponse
  json.Unmarshal(body, &startResp)

  fmt.Printf("Workflow started: %s\n", startResp.WorkflowID)

  // Poll for status
  statusURL := fmt.Sprintf("https://app.phinite.ai/api/v1/ai/trigger/status/{workspace_id}/%s", startResp.WorkflowID)

  for {
    statusReq, _ := http.NewRequest("GET", statusURL, nil)
    statusReq.Header.Add("Authorization", "Bearer workspace_api_key")

    statusRes, _ := client.Do(statusReq)
    statusBody, _ := io.ReadAll(statusRes.Body)
    statusRes.Body.Close()

    var statusResp StatusResponse
    json.Unmarshal(statusBody, &statusResp)

    fmt.Printf("Status: %s, Logs: %d\n", statusResp.Status, len(statusResp.Logs))

    if statusResp.Status == "completed" || statusResp.Status == "failed" {
      fmt.Printf("Final result: %s\n", string(statusBody))
      break
    }

    time.Sleep(5 * time.Second)
  }
}

Java - Single Endpoint

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,
  "{\n    \"message\": \"start the task\",\n    \"user_variables\": {\n      \"key1\": \"value1\",\n      \"key2\": \"value2\"\n    }\n  }");

Request request = new Request.Builder()
  .url("https://app.phinite.ai/api/v1/ai/trigger/{workspace_id}/{trigger_id}/{environment}")
  .method("POST", body)
  .addHeader("Authorization", "Bearer workspace_api_key")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

PHP - Single Endpoint

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app.phinite.ai/api/v1/ai/trigger/{workspace_id}/{trigger_id}/{environment}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode([
    "message" => "start the task",
    "user_variables" => [
      "key1" => "value1",
      "key2" => "value2"
    ]
  ]),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer workspace_api_key'
  ),
));

$response = curl_exec($curl);
curl_close($curl);

echo $response;
?>

Ruby - Single Endpoint

require "uri"
require "json"
require "net/http"

url = URI("https://app.phinite.ai/api/v1/ai/trigger/{workspace_id}/{trigger_id}/{environment}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer workspace_api_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "message" => "start the task",
  "user_variables" => {
    "key1" => "value1",
    "key2" => "value2"
  }
})

response = https.request(request)
puts response.read_body

---

Error Responses

401 Unauthorized

{
  "detail": "Invalid authentication credentials"
}

422 Unprocessable Entity

{
  "detail": [
    {
      "type": "dict_type",
      "loc": [
        "body",
        "user_variables"
      ],
      "msg": "Input should be a valid dictionary",
      "input": "string"
    }
  ]
}

500 Server Error

{
  "detail": "Process query failed: Internal server error"
}

---

Common Use Cases

• Automated incident response from monitoring systems
• Scheduled data processing and reporting
• Webhook-triggered workflows from external platforms (Jira, etc.)
• Background batch processing with real-time progress tracking
• Long-running data transformation and enrichment tasks
• Periodic system health checks and maintenance routines

---

Notes & Best Practices

Caution

Choose the right execution mode: Use single endpoint API only for simple flows under 120-150 seconds. Use background task for most autonomous workflows. Use cron job for scheduled, recurring tasks.

• Validate bearer tokens: Always verify authentication in DEV environment before deploying to PROD.
• Use user_variables for context: Pass structured data through user_variables instead of embedding everything in the message field.
• Poll status intelligently: When using background tasks, implement appropriate polling intervals (e.g., every 5-10 seconds) to check status without overwhelming the API.
• Monitor execution time: Be aware of the 2700-second maximum for background tasks. Design flows to complete within this limit.
• Test thoroughly: Always test in DEV environment before promoting to UAT and PROD.
• Keep triggers descriptive: Use clear, meaningful names for triggers to facilitate internal reference and debugging.
• Handle webhooks appropriately: For Jira and other webhook integrations, ensure the integration is properly configured with the correct secret before testing.