Skip to main content
POST
/
runs
Start a Workflow Run
curl --request POST \
  --url https://api.getnen.ai/runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "workflow_id": "12345678-1234-1234-1234-123456789abc",
  "workflow_params": {
    "PATIENT_NAME": "Jane Doe",
    "DATE_OF_BIRTH": "1990-01-15"
  },
  "secure_workflow_params": {
    "password": "s3cret-passw0rd"
  },
  "webhook_callback": "https://your-domain.com/webhook"
}
'
{
  "message": "Job accepted for processing.",
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "workflowId": "12345678-1234-1234-1234-123456789abc"
}
This endpoint returns immediately with a 202 Accepted response. The actual workflow execution happens in the background, and you’ll receive updates via your webhook callback URL.

​
Next Steps

After starting a workflow run, you’ll receive status updates at your webhook endpoint as the job progresses.

Handle webhook callbacks

Learn how to receive and verify webhook updates for your workflow runs

​
Best Practices

Always store the returned messageId in your database. You’ll need it to:
  • Correlate webhook callbacks with the original request
  • Track workflow status
  • Debug issues with support
# Example: Store in database
run = WorkflowRun.objects.create(
    message_id=response['messageId'],
    workflow_id=response['workflowId'],
    status='processing',
    created_at=datetime.now()
)
Validate your workflow parameters before making the API call to avoid errors:
function validateWorkflowParams(params, workflowType) {
  const requiredFields = getRequiredFields(workflowType);
  
  for (const field of requiredFields) {
    if (!params[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }
  
  return true;
}
Never hardcode API keys or secrets in your code:
# .env file
NEN_API_KEY=your_api_key_here
WEBHOOK_CALLBACK_URL=https://your-domain.com/webhook

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('NEN_API_KEY')
webhook_url = os.getenv('WEBHOOK_CALLBACK_URL')

​
Troubleshooting

Symptoms: Request takes too long and eventually times outSolutions:
  • Check your internet connection
  • Verify the API endpoint URL is correct
  • Increase the request timeout in your HTTP client
  • Check if there are any network restrictions or firewalls
# Set a reasonable timeout
response = requests.post(url, json=payload, timeout=30)
Symptoms: Receiving 400 error about invalid parametersSolutions:
  • Check your workflow configuration to see required parameters
  • Ensure parameter names match exactly (case-sensitive)
  • Verify data types are correct (strings, numbers, booleans)
  • Remove any extra parameters not defined in the workflow
// Log parameters before sending
console.log('Sending parameters:', JSON.stringify(params, null, 2));
Symptoms: Run starts but no webhooks arriveSolutions:
  • Ensure your webhook URL is publicly accessible
  • Test your webhook URL with tools like webhook.site
  • Check firewall rules and security groups
  • Verify SSL certificate is valid
  • Ensure your server can handle POST requests
# Test your webhook endpoint
curl -X POST https://your-domain.com/webhook \
  -H 'Content-Type: application/json' \
  -d '{"test": "data"}'

Authorizations

​
x-api-key
string
header
required

Your Nen API key. Requests that include secure_workflow_params must additionally be HMAC-signed — see Secure Parameters.

Body

application/json

Workflow run configuration

​
workflow_id
string<uuid>
required

Unique identifier for the workflow to execute

Example:

"12345678-1234-1234-1234-123456789abc"

​
workflow_params
object

Parameters passed to your workflow's Params model. Must match the Pydantic shape the workflow declares.

Example:
{
  "PATIENT_NAME": "Jane Doe",
  "DATE_OF_BIRTH": "1990-01-15"
}
​
secure_workflow_params
object

Secret parameters passed to your workflow's SecureParams model. Requires HMAC-signed requests — see Secure Parameters. Rejected with 403 when sent using only x-api-key.

Example:
{ "password": "s3cret-passw0rd" }
​
webhook_callback
string<uri>

URL where status updates will be sent. When omitted, results are only available via the retrieval endpoint.

Example:

"https://your-domain.com/webhook"

Response

Job accepted for processing

​
message
string

Confirmation message

Example:

"Job accepted for processing."

​
messageId
string<uuid>

Unique identifier for this workflow execution

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
workflowId
string<uuid>

The workflow ID that was submitted

Example:

"12345678-1234-1234-1234-123456789abc"