Skip to main content

​
Welcome to the Nen API

The Nen API enables you to programmatically trigger and manage automated workflows. Built for reliability and ease of use, our API uses simple REST principles with JSON payloads and standard HTTP response codes.

​
Two API surfaces

Nen’s HTTP API has two surfaces. Both live on the same host and share the same auth header — only the paths differ.
SurfaceBase URLAuth headerWhat it does
Managed workflowshttps://api.getnen.aix-api-key: <key>Trigger workflow runs, receive webhook callbacks. This page and the endpoints under /api-reference/endpoint/ document this surface.
Desktop APIhttps://api.getnen.aix-api-key: <key>Create, list, and control cloud desktops; discover and execute computer tools. Documented in Computer-Use Desktops and Tools.

​
Quick Start

Get started with the Nen API in three steps:
1

Get your API key

Retrieve your API key from your engineering contact. Keep this secure and never expose it in client-side code.
2

Start a workflow run

Use the Start a Workflow Run endpoint to trigger your workflow with the required parameters.
3

Handle webhook callbacks

Implement a webhook endpoint to retrieve workflow payloads such as documents and execution results.

​
Core Endpoints

Start a Workflow Run

Trigger workflow execution with custom parameters

Webhook Integration

Receive real-time status updates and results

​
Authentication

All API requests require authentication using an API key sent in the x-api-key header. 
curl -X POST 'https://api.getnen.ai/runs' \
  -H 'x-api-key: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflow_id": "12345678-1234-1234-1234-123456789abc",
    "workflow_params": {
      "PATIENT_NAME": "Jane Doe"
    },
    "webhook_callback": "https://your-domain.com/webhook"
  }'
Keep your API key secure. Never commit it to version control or expose it in client-side code. Use environment variables to store your key safely.

​
Response Format

All API responses use JSON format with standard HTTP status codes:
  • 2xx: Success - Your request was processed successfully
  • 4xx: Client Error - There was an issue with your request
  • 5xx: Server Error - Something went wrong on our end

​
Success Response Example

{
  "message": "Job accepted for processing.",
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "workflowId": "12345678-1234-1234-1234-123456789abc"
}

​
Error Response Example

{
  "error": "Invalid request",
  "message": "Missing required field: workflow_id"
}

​
Workflow Execution Flow

1

Submit workflow

POST to /runs with your workflow ID, parameters, and webhook callback URL. You’ll receive an immediate 202 Accepted response with a unique messageId.
2

Processing begins

Your workflow starts executing in the background. You’ll receive a webhook callback with status processing.
3

Receive results

When complete, you’ll receive another webhook with status success or failed, including presigned URLs to download results.

​
Best Practices

Store your API key and webhook URLs in environment variables, not in your source code.
# .env
NEN_API_KEY=your_api_key_here
WEBHOOK_CALLBACK_URL=https://your-domain.com/webhook
Always verify webhook signatures to ensure requests are genuinely from Nen. See the Webhook Security section for implementation details.
Set up monitoring to alert you if webhooks stop arriving. This helps catch issues with your webhook endpoint early.

​
Need Help?

Start a Workflow Run

Detailed guide with code examples

Webhook Integration

Complete webhook implementation guide