Skip to main content

​
Overview

Jinba Flow provides REST API endpoints that allow you to execute published workflows programmatically. Once a workflow is published, you can call it from external systems, webhooks, or any application that can make HTTP requests.

​
API Access

​
Prerequisites

To use the API, you need:
  1. Published Workflow: The workflow must be published (see Publish)
  2. API Key: An API key is automatically generated when you publish a workflow
  3. Authentication: Use the API key in the Authorization header

​
API Endpoints

​
Run Published Workflow

Endpoint: POST /api/v2/external/flows/{flowId}/published-run Authentication: Bearer token (API key) Request Body: 
{
  "args": [
    {
      "name": "input1",
      "value": "example value"
    }
  ],
  "mode": "sync" // or "async"
}
Response: Workflow execution result

​
Authentication

​
API Keys

When you publish a workflow, an API key is automatically generated:
  • Automatic Generation: Created when you first publish
  • Flow-Scoped: Each workflow has its own API key
  • Secure Storage: Keys are stored securely in your workspace
  • Viewing Keys: Access keys from workflow settings

​
Using API Keys

Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
Security Best Practices:
  • Never share API keys publicly
  • Store keys securely in environment variables
  • Rotate keys regularly if compromised
  • Use different keys for different environments

​
Calling Workflows via API

​
Synchronous Execution

Synchronous execution waits for the workflow to complete before returning: 
curl -X POST https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      {"name": "input1", "value": "example"}
    ],
    "mode": "sync"
  }'
Characteristics:
  • Blocking: Request waits for completion
  • Immediate Response: Returns result when workflow finishes
  • Timeout: May timeout for long-running workflows
  • Use Case: When you need immediate results

​
Asynchronous Execution

Asynchronous execution returns immediately and runs the workflow in the background: 
curl -X POST https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      {"name": "input1", "value": "example"}
    ],
    "mode": "async"
  }'
Characteristics:
  • Non-Blocking: Returns immediately with run ID
  • Background Execution: Workflow runs asynchronously
  • Status Check: Use run ID to check status later
  • Use Case: For long-running workflows or fire-and-forget scenarios

​
Input Arguments

​
Argument Format

Arguments are passed as an array of name-value pairs: 
{
  "args": [
    {
      "name": "parameter_name",
      "value": "parameter_value"
    }
  ]
}

​
Argument Types

Arguments can be:
  • Strings: Text values
  • Numbers: Numeric values
  • Booleans: True/false values
  • Objects: Complex nested data structures
  • Arrays: Lists of values

​
Example Arguments

{
  "args": [
    {
      "name": "email",
      "value": "user@example.com"
    },
    {
      "name": "count",
      "value": 10
    },
    {
      "name": "options",
      "value": {
        "includeMetadata": true,
        "format": "json"
      }
    }
  ]
}

​
Response Format

​
Success Response

{
  "status": "success",
  "result": {
    // Workflow output
  },
  "stepOutputs": {
    "step_1": {
      "status": "success",
      "result": {}
    }
  }
}

​
Error Response

{
  "status": "failed",
  "error": {
    "name": "ErrorType",
    "value": "Error message",
    "traceback": "Stack trace"
  },
  "stepOutputs": {
    "step_1": {
      "status": "failed",
      "error": {
        "name": "StepError",
        "value": "Step error message"
      }
    }
  }
}

​
API Usage Examples

​
Python Example

import requests

url = "https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "args": [
        {"name": "input1", "value": "example"}
    ],
    "mode": "sync"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

​
JavaScript/Node.js Example

const fetch = require('node-fetch');

const url = 'https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};
const body = {
  args: [
    { name: 'input1', value: 'example' }
  ],
  mode: 'sync'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(body)
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

​
Webhook Integration

You can call workflows from webhooks: 
# Example webhook payload
curl -X POST https://api.jinba.dev/api/v2/external/flows/{flow-id}/published-run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "args": [
      {"name": "webhook_data", "value": "{\"event\": \"user_signup\", \"user_id\": 123}"}
    ]
  }'

​
Error Handling

​
Common Errors

​
401 Unauthorized

Cause: Invalid or missing API key Solution: Verify your API key is correct and included in the Authorization header

​
404 Not Found

Cause: Workflow not found or not published Solution:
  • Verify the workflow ID is correct
  • Ensure the workflow is published
  • Check that the workflow is not archived

​
403 Forbidden

Cause: API key doesn’t have access to this workflow Solution: Verify the API key is scoped to the correct workflow or workspace

​
400 Bad Request

Cause: Invalid request format or missing required arguments Solution:
  • Check request body format
  • Verify all required arguments are provided
  • Validate argument types match workflow expectations

​
Retry Logic

For production applications, implement retry logic: 
import time
import requests

def call_workflow_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data, timeout=30)
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:  # Rate limit
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                response.raise_for_status()
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    return None

​
Rate Limiting

API requests may be subject to rate limiting:
  • Rate Limits: Limits may apply based on your subscription plan
  • 429 Status: Returns 429 Too Many Requests when limit exceeded
  • Retry-After: Header indicates when to retry
  • Best Practice: Implement exponential backoff for retries

​
API Key Management

​
Viewing API Keys

  1. Open your published workflow
  2. Navigate to workflow settings
  3. Go to API or Publish Settings section
  4. View your API key

​
Regenerating API Keys

If your API key is compromised:
  1. Go to workflow settings
  2. Navigate to API section
  3. Regenerate the API key
  4. Update all applications using the old key
Important: Regenerating a key invalidates the old key immediately.

​
Best Practices

  1. Use Environment Variables: Store API keys in environment variables, not in code
  2. Error Handling: Implement proper error handling and retry logic
  3. Timeout Configuration: Set appropriate timeouts for API calls
  4. Logging: Log API calls for debugging and monitoring
  5. Security: Never commit API keys to version control
  6. Async for Long Tasks: Use async mode for long-running workflows
  7. Input Validation: Validate inputs before sending to API
  • Publish - Learn about publishing workflows
  • Scheduling - Learn about scheduling workflows
  • Workspace - Learn about workspace management