API - jinba

The triggers panel. Find the endpoint URL, secret key, and a ready-to-use cURL snippet

API key management in workspace settings. Issue API keys for connecting Jinba App and using MCP tools

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:

Published Workflow: The workflow must be published (see Publish)
API Key: An API key is automatically generated when you publish a workflow
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

Open your published workflow
Navigate to workflow settings
Go to API or Publish Settings section
View your API key

Regenerating API Keys

If your API key is compromised:

Go to workflow settings
Navigate to API section
Regenerate the API key
Update all applications using the old key

Important: Regenerating a key invalidates the old key immediately.

Best Practices

Use Environment Variables: Store API keys in environment variables, not in code
Error Handling: Implement proper error handling and retry logic
Timeout Configuration: Set appropriate timeouts for API calls
Logging: Log API calls for debugging and monitoring
Security: Never commit API keys to version control
Async for Long Tasks: Use async mode for long-running workflows
Input Validation: Validate inputs before sending to API

Publish - Learn about publishing workflows
Scheduling - Learn about scheduling workflows
Workspace - Learn about workspace management

​Overview

​API Access

​Prerequisites

​API Endpoints

​Run Published Workflow

​Authentication

​API Keys

​Using API Keys

​Calling Workflows via API

​Synchronous Execution

​Asynchronous Execution

​Input Arguments

​Argument Format

​Argument Types

​Example Arguments

​Response Format

​Success Response

​Error Response

​API Usage Examples

​Python Example

​JavaScript/Node.js Example

​Webhook Integration

​Error Handling

​Common Errors

​401 Unauthorized

​404 Not Found

​403 Forbidden

​400 Bad Request

​Retry Logic

​Rate Limiting

​API Key Management

​Viewing API Keys

​Regenerating API Keys

​Best Practices

​Related Features