Skip to main content
POST
/
api
/
v1
/
runtime
/
agents
Create new agent (CLI/SDK)
curl --request POST \
  --url https://api.runflow.ai/api/v1/runtime/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer Support Bot",
  "description": "AI-powered customer support agent",
  "category": "CUSTOMER_SUPPORT",
  "code": "export function main() { return \"Hello World\"; }",
  "subcategory": "TIER_1_SUPPORT",
  "status": "INACTIVE",
  "logo": "https://example.com/logo.png",
  "repositoryUrl": "https://github.com/user/agent-repo",
  "endpointUrl": "https://api.example.com/agent/endpoint",
  "fileTree": [
    {
      "name": "src",
      "type": "folder",
      "children": [
        {
          "name": "index.ts",
          "type": "file",
          "content": "export function main() { return \"Hello World\"; }"
        }
      ]
    }
  ],
  "language": "typescript",
  "branch": "main",
  "commit": "abc123def456",
  "tags": [
    "ai",
    "customer-support",
    "chatbot"
  ],
  "templateId": "starter"
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Customer Support Bot",
  "description": "AI-powered customer support agent",
  "category": "CUSTOMER_SUPPORT",
  "status": "ACTIVE",
  "code": "export function main() { return \"Hello World\"; }",
  "language": "typescript",
  "branch": "main",
  "tags": [
    "ai",
    "customer-support",
    "chatbot"
  ],
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z",
  "tenantId": "123e4567-e89b-12d3-a456-426614174000",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "subcategory": "TIER_1_SUPPORT",
  "lastDeploy": "2025-01-01T00:00:00.000Z",
  "logo": "https://example.com/logo.png",
  "repositoryUrl": "https://github.com/user/agent-repo",
  "endpointUrl": "https://chatbot.acme.runflow.ai",
  "fileTree": [
    {
      "name": "src",
      "type": "folder",
      "children": [
        {
          "name": "index.ts",
          "type": "file",
          "content": "export function main() { return \"Hello World\"; }"
        }
      ]
    }
  ],
  "commit": "abc123def456",
  "stagingCommit": "2025-01-01T00-00-00-000Z",
  "stagingEndpointUrl": "https://staging.runflow.ai/agent/abc123",
  "_count": {
    "executions": 15,
    "dataSources": 3,
    "triggers": 2
  },
  "repositoryName": "agent-repo",
  "scheduleArn": "arn:aws:scheduler:us-east-1:123456789012:schedule/default/my-schedule",
  "newEngine": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt

Use this file to discover all available pages before exploring further.

Body

application/json
​
name
string
required

Agent name

Required string length: 2 - 100
Example:

"Customer Support Bot"

​
description
string
required

Agent description

Required string length: 10 - 500
Example:

"AI-powered customer support agent"

​
category
enum<string>
required

Agent category

Available options:
SALES,
CUSTOMER_SUPPORT,
VOICE,
OPERATIONS,
FINANCIAL_PREVENTION,
FINANCIAL_RECOVERY,
MARKETING,
ANALYTICS
Example:

"CUSTOMER_SUPPORT"

​
code
string
required

Agent source code

Example:

"export function main() { return \"Hello World\"; }"

​
subcategory
enum<string>

Agent subcategory for more specific classification

Available options:
SDR_OUTBOUND,
SDR_INBOUND,
ACCOUNT_MANAGER,
SALES_CLOSER,
LEAD_QUALIFIER,
TIER_1_SUPPORT,
TECHNICAL_SUPPORT,
ESCALATION_HANDLER,
CHAT_SUPPORT,
COLD_CALLING,
CUSTOMER_SERVICE_VOICE,
APPOINTMENT_SETTER,
SURVEY_CALLER,
DATA_PROCESSOR,
WORKFLOW_AUTOMATOR,
QUALITY_CHECKER,
REPORT_GENERATOR,
FRAUD_DETECTOR,
RISK_ASSESSOR,
COMPLIANCE_MONITOR,
DEBT_COLLECTOR,
PAYMENT_NEGOTIATOR,
RECOVERY_SPECIALIST,
CONTENT_CREATOR,
CAMPAIGN_MANAGER,
SOCIAL_MEDIA_MANAGER,
EMAIL_MARKETER,
DATA_ANALYST,
PERFORMANCE_TRACKER,
INSIGHT_GENERATOR,
DASHBOARD_CREATOR
Example:

"TIER_1_SUPPORT"

​
status
enum<string>
default:INACTIVE

Agent status

Available options:
ACTIVE,
INACTIVE,
ERROR,
DEPLOYING
Example:

"INACTIVE"

Agent logo URL

Maximum string length: 500
Example:

"https://example.com/logo.png"

​
repositoryUrl
string

Repository URL

Maximum string length: 500
Example:

"https://github.com/user/agent-repo"

​
endpointUrl
string

Agent endpoint URL

Maximum string length: 500
Example:

"https://api.example.com/agent/endpoint"

​
fileTree
object

File tree structure for IDE-like interface

Example:
[
  {
    "name": "src",
    "type": "folder",
    "children": [
      {
        "name": "index.ts",
        "type": "file",
        "content": "export function main() { return \"Hello World\"; }"
      }
    ]
  }
]
​
language
string
default:typescript

Programming language

Maximum string length: 50
Example:

"typescript"

​
branch
string
default:main

Git branch

Maximum string length: 100
Example:

"main"

​
commit
string

Git commit hash

Maximum string length: 100
Example:

"abc123def456"

​
tags
string[]

Agent tags

Example:
["ai", "customer-support", "chatbot"]
​
templateId
enum<string>

Template ID for project initialization (from /public/templates)

Available options:
starter,
rag-agent,
webhook-handler
Maximum string length: 50
Example:

"starter"

Response

201 - application/json

Agent created successfully.

​
id
string
required

Agent unique identifier

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
name
string
required

Agent name

Example:

"Customer Support Bot"

​
description
string
required

Agent description

Example:

"AI-powered customer support agent"

​
category
enum<string>
required

Agent category

Available options:
SALES,
CUSTOMER_SUPPORT,
VOICE,
OPERATIONS,
FINANCIAL_PREVENTION,
FINANCIAL_RECOVERY,
MARKETING,
ANALYTICS
Example:

"CUSTOMER_SUPPORT"

​
status
enum<string>
required

Agent status

Available options:
ACTIVE,
INACTIVE,
ERROR,
DEPLOYING
Example:

"ACTIVE"

​
code
string
required

Agent source code

Example:

"export function main() { return \"Hello World\"; }"

​
language
string
required

Programming language

Example:

"typescript"

​
branch
string
required

Git branch

Example:

"main"

​
tags
string[]
required

Agent tags

Example:
["ai", "customer-support", "chatbot"]
​
createdAt
string<date-time>
required

Creation timestamp

Example:

"2025-01-01T00:00:00.000Z"

​
updatedAt
string<date-time>
required

Last update timestamp

Example:

"2025-01-01T00:00:00.000Z"

​
tenantId
string
required

Tenant ID that the agent belongs to

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
userId
string
required

User ID that owns the agent

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
subcategory
enum<string>

Agent subcategory for more specific classification

Available options:
SDR_OUTBOUND,
SDR_INBOUND,
ACCOUNT_MANAGER,
SALES_CLOSER,
LEAD_QUALIFIER,
TIER_1_SUPPORT,
TECHNICAL_SUPPORT,
ESCALATION_HANDLER,
CHAT_SUPPORT,
COLD_CALLING,
CUSTOMER_SERVICE_VOICE,
APPOINTMENT_SETTER,
SURVEY_CALLER,
DATA_PROCESSOR,
WORKFLOW_AUTOMATOR,
QUALITY_CHECKER,
REPORT_GENERATOR,
FRAUD_DETECTOR,
RISK_ASSESSOR,
COMPLIANCE_MONITOR,
DEBT_COLLECTOR,
PAYMENT_NEGOTIATOR,
RECOVERY_SPECIALIST,
CONTENT_CREATOR,
CAMPAIGN_MANAGER,
SOCIAL_MEDIA_MANAGER,
EMAIL_MARKETER,
DATA_ANALYST,
PERFORMANCE_TRACKER,
INSIGHT_GENERATOR,
DASHBOARD_CREATOR
Example:

"TIER_1_SUPPORT"

​
lastDeploy
string<date-time>

Last deployment timestamp

Example:

"2025-01-01T00:00:00.000Z"

Agent logo URL

Example:

"https://example.com/logo.png"

​
repositoryUrl
string

Repository URL

Example:

"https://github.com/user/agent-repo"

​
endpointUrl
string

Agent endpoint URL (populated by provisioning service)

Example:

"https://chatbot.acme.runflow.ai"

​
fileTree
object

File tree structure for IDE-like interface

Example:
[
  {
    "name": "src",
    "type": "folder",
    "children": [
      {
        "name": "index.ts",
        "type": "file",
        "content": "export function main() { return \"Hello World\"; }"
      }
    ]
  }
]
​
commit
string

Git commit hash

Example:

"abc123def456"

​
stagingCommit
string

Staging commit hash (latest deploy to staging)

Example:

"2025-01-01T00-00-00-000Z"

​
stagingEndpointUrl
string

Staging endpoint URL

Example:

"https://staging.runflow.ai/agent/abc123"

​
_count
object

Agent related statistics

Example:
{
  "executions": 15,
  "dataSources": 3,
  "triggers": 2
}
​
repositoryName
string

Repository name

Example:

"agent-repo"

​
scheduleArn
string

AWS Scheduler ARN

Example:

"arn:aws:scheduler:us-east-1:123456789012:schedule/default/my-schedule"

​
newEngine
boolean

Use new executor-engine (Go) instead of legacy execution-engine (NestJS)

Example:

true