API Endpoints - Railway Integration Service

← Back to Dashboard

📦 Service Management

POST

Create Service

/api/v2/admin/services/create

Create a new V2 service programmatically without needing to upload a template

▼

📋 What This Does:

Creates a service definition in the database (metadata only)
Does NOT create actions - use this to set up a service first, then add actions later
Optionally creates system parameters (API keys, secrets, config values)
Supports tenant-based parameters (multi-tenant support)
Uses UPSERT pattern - updates if service already exists

Service Key *

Service Name *

Service Description

Required System Parameters

Optional System Parameters

Tenant Name (optional) For tenant-scoped system parameters

POST

Upload Service Template

/api/v2/admin/services/upload

Upload a V2 service template (JSON file) to create or update a service with all its actions

▼

📋 What This Does:

Uploads a complete V2 service template (JSON file)
Creates or updates the service definition in database
Creates or updates all actions defined in the template
Validates the template structure before uploading
Supports connector configuration (UI metadata)

📤 Request

Content-Type: multipart/form-data

Form Field: template (file)

curl -X POST "${baseUrl}/api/v2/admin/services/upload" \\
  -F "template=@service-template.json"

📥 Response (Success)

{
  "success": true,
  "message": "Service template uploaded successfully",
  "service": {
    "serviceKey": "monday",
    "serviceName": "Monday.com",
    "actionCount": 7
  },
  "actions": [
    {
      "actionName": "create-item",
      "status": "created"
    }
  ]
}

💡 Tip: The template file must be valid JSON and follow the V2 service template structure. See the template validator for details.

GET

List All Services

/api/v2/admin/services

Get all V2 services with their metadata, action counts, and status

▼

📋 What This Does:

Returns all V2 services in the system
Includes action counts for each service
Shows service status (enabled/disabled)
Includes metadata and connector configuration

📤 Request

No request body required

curl -X GET "${baseUrl}/api/v2/admin/services"

📥 Response (Success)

{
  "success": true,
  "services": [
    {
      "key": "monday",
      "name": "Monday.com",
      "description": "Monday.com integration",
      "action_count": 7,
      "enabled": true,
      "created_at": "2025-10-15T10:00:00Z"
    },
    {
      "key": "aws-s3",
      "name": "AWS S3",
      "description": "AWS S3 file storage",
      "action_count": 4,
      "enabled": true,
      "created_at": "2025-10-20T14:30:00Z"
    }
  ]
}

GET

Get Service Actions

/api/v2/admin/services/:serviceKey/actions

Get all actions for a specific service

▼

📋 What This Does:

Returns all actions for a specific service
Includes action metadata (name, description, enabled status)
Shows HTTP method and version for each action
Useful for discovering available actions in a service

📤 Request

URL Parameter: serviceKey (required)

curl -X GET "${baseUrl}/api/v2/admin/services/monday/actions"

Example: Replace monday with your service key

📥 Response (Success)

{
  "success": true,
  "actions": [
    {
      "name": "create-item",
      "displayName": "Create Monday Item",
      "description": "Creates a new item in Monday.com",
      "method": "POST",
      "enabled": true,
      "version": "1.0.0"
    },
    {
      "name": "get-item",
      "displayName": "Get Monday Item",
      "description": "Retrieves an item from Monday.com",
      "method": "GET",
      "enabled": true,
      "version": "1.0.0"
    }
  ]
}

DELETE

Delete Service

/api/v2/admin/services/:serviceKey

Delete a service and all related data (actions, logs, tests). This action cannot be undone

▼

⚠️ Warning: This is a destructive operation!

Permanently deletes the service from database
Deletes all actions associated with the service
Deletes execution logs and test results
Deletes user traces related to the service
This action cannot be undone!

📤 Request

URL Parameter: serviceKey (required)

No request body required

curl -X DELETE "${baseUrl}/api/v2/admin/services/monday"

📥 Response (Success)

{
  "success": true,
  "message": "Service deleted successfully",
  "deleted": {
    "serviceKey": "monday",
    "serviceName": "Monday.com",
    "actionsDeleted": 7,
    "executionLogsDeleted": 1250,
    "deletedAt": "2025-12-29T16:00:00Z"
  }
}

⚡ Action Management

POST

Create Action

/api/action-generator/create

Create a V2 action from a JavaScript or Python function

▼

📋 What This Does:

Converts JavaScript or Python functions into V2 action flows
Creates helper functions from your code
Generates api_flow with steps (validate_payload, call_helper, format_response, etc.)
Stores action in action_definitions table
Can create service automatically if it doesn't exist (when full service definition provided)
Supports basic actions (function-based) and major actions (flow-based with call_v2_action)

🔄 Action Types:

Basic Action: Function-based - converts function code to helper, generates flow automatically
Major Action: Flow-based - uses custom flow with call_v2_action steps (no function code needed)

Service *

Use Existing Service

Create New Service

Service Key * Service must already exist in the system

Action Type *

Basic Action (Function-based)

Major Action (Flow-based, uses call_v2_action)

Function Code *

Helper Parameters (comma-separated, for documentation) These are for documentation only. Actual parameters come from functionCode.

Helper Returns (for documentation) What the helper function returns (for documentation only).

Action Name *

Display Name *

Description *

Language *

HTTP Method *

Payload Schema (JSON)

ReadMe Category (optional)

Automatically upload to ReadMe.io

POST

Create Simple Action (Direct Execution)

/api/action-generator/create-simple

Create a simplified action with direct function execution - no flow generation

▼

📋 What This Does:

Creates a simplified action with direct function execution
No flow generation - function code is stored directly in metadata
No helper conversion - executes function code as-is
Uses execution_type: 'direct' in metadata
System parameters are automatically injected into function context
Faster execution - no flow step overhead
Service must already exist (cannot create service automatically)

🔄 vs. Create Action (/create):

create-simple: Direct execution, no flow, faster, simpler
create: Flow-based, converts to helpers, more flexible, supports service creation
Use create-simple when you want direct function execution without flow overhead
Use create when you need flow steps, helper functions, or service auto-creation

📤 Request

Required Fields:

serviceKey - Service must already exist
actionName - Unique action name
displayName - Human-readable name
description - Action description
functionCode - JavaScript/Python function code (as string)
language - "javascript" or "python"
httpMethod - GET, POST, PUT, DELETE, PATCH
systemParameters - Array of parameter keys (e.g., ["MONDAY_API_KEY"])

Optional Fields:

payloadSchema - JSON schema for validation
responseSchema - JSON schema for response
version - Action version (default: "1.0.0")
creator - Creator identifier

{
  "serviceKey": "rm_playground_database",
  "actionName": "create-lead",
  "displayName": "Create Lead",
  "description": "Creates a new lead in the database",
  "functionCode": "async function executeAction(payload, context) {\n  const client = await context.db.connect();\n  try {\n    // Your function code here\n    const result = await client.query('INSERT INTO leads...');\n    return { success: true, data: result.rows[0] };\n  } finally {\n    client.release();\n  }\n}",
  "language": "javascript",
  "httpMethod": "POST",
  "systemParameters": ["DATABASE_URL", "MONDAY_API_KEY"],
  "payloadSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "email": { "type": "string" }
    },
    "required": ["name", "email"]
  },
  "version": "1.0.0"
}

📥 Response (Success)

{
  "success": true,
  "service": {
    "key": "rm_playground_database",
    "name": "RM Playground Database"
  },
  "action": {
    "name": "create-lead",
    "displayName": "Create Lead",
    "url": "https://refreshing-amazement-production.up.railway.app/api/v2/execute/rm_playground_database/create-lead",
    "type": "direct",
    "version": "1.0.0"
  },
  "method": "POST",
  "execution": {
    "type": "direct",
    "systemParameters": ["DATABASE_URL", "MONDAY_API_KEY"],
    "functionCodeLength": 245
  },
  "message": "Simplified action created and ready to use (direct function execution)",
  "testCommand": "curl -X POST https://refreshing-amazement-production.up.railway.app/api/v2/execute/rm_playground_database/create-lead -H \"Content-Type: application/json\" -d '{\"test\": true}'"
}

🔄 Execution Flow

Action Created: Function code stored in metadata.function_code
Execution Triggered: POST to /api/v2/execute/{serviceKey}/{actionName}
Direct Executor: Detects execution_type: 'direct' in metadata
System Parameters: Automatically fetched and injected into context.systemParams
Function Execution: Function code executed directly (no flow steps)
Database Access: context.db provides PostgreSQL connection pool
Response: Function return value is sent as response

💡 Important: The function must be named executeAction(payload, context). The context object provides db (database pool), systemParams (system parameters), and logger.

Service Key * Service must already exist

Action Name *

Display Name *

Description *

Function Code * Must be named executeAction(payload, context)

Language *

HTTP Method *

System Parameters * (comma-separated) Array of parameter keys that will be injected into context

Payload Schema (JSON, optional)

Response Schema (JSON, optional)

Version (optional)

POST

Manage Action

/api/v2/admin/actions/:serviceKey/:actionName

Update, delete, enable, disable, or archive an existing action

▼

📋 What This Does:

Update: Modify action metadata (displayName, description, version, etc.) - partial updates supported
Delete: Permanently remove action from database (cannot be undone)
Enable: Enable a disabled action (sets enabled = true)
Disable: Disable an action (soft delete, sets enabled = false)
Archive: Archive an action (same as disable, semantic difference)

✨ Features:

Partial Updates: Only provide fields you want to change
Enhanced Error Messages: Specific error details with suggestions
Validation: Validates apiFlow, httpMethod, enabled fields

Request Body Schema

Operation Types:

Note: For update operation, all fields except operation are optional. Only provided fields will be updated.

Service Key *

Action Name *

Operation *

Update Fields (all optional - only provided fields will be updated)

Display Name

Description

HTTP Method

Enabled

Version

Payload Schema (JSON)

Response Schema (JSON)

API Flow (JSON Array) Array of flow step objects. Each step must have "id" and "type" properties.

Metadata (JSON)

🔐 System Parameters

POST

Create System Parameter

/api/admin/system-parameters

Create a new system parameter (API keys, secrets, configuration values)

▼

📋 What This Does:

Creates a system parameter (API keys, secrets, config values)
Stores credentials and configuration for V2 services
Supports encryption (future feature)
Parameters are service-scoped or global
Used by V2 actions via get_system_params step

📤 Request

{
  "serviceKey": "monday",
  "paramKey": "MONDAY_API_KEY",
  "paramValue": "your-api-key-here",
  "displayName": "Monday.com API Key",
  "description": "API key for Monday.com authentication",
  "isRequired": true,
  "category": "authentication",
  "isEncrypted": false
}

📥 Response (Success)

{
  "success": true,
  "message": "System parameter created successfully",
  "data": {
    "id": 123,
    "serviceKey": "monday",
    "paramKey": "MONDAY_API_KEY",
    "displayName": "Monday.com API Key",
    "isRequired": true,
    "category": "authentication",
    "created_at": "2025-12-29T16:00:00Z"
  }
}

💡 Tip: Use the System Parameters UI page for easier management. This endpoint is for programmatic access.

GET

List System Parameters

/api/admin/system-parameters

Get all system parameters with optional filtering by service key

▼

📋 What This Does:

Returns all system parameters in the system
Optional query parameter to filter by service key
Shows parameter metadata (display name, description, category)
Includes encryption status and required flag

📤 Request

Query Parameters (optional):

service_key - Filter by service (e.g., ?service_key=monday)

curl -X GET "${baseUrl}/api/admin/system-parameters?service_key=monday"

📥 Response (Success)

{
  "success": true,
  "data": [
    {
      "id": 123,
      "serviceKey": "monday",
      "paramKey": "MONDAY_API_KEY",
      "displayName": "Monday.com API Key",
      "description": "API key for Monday.com",
      "isRequired": true,
      "category": "authentication",
      "isEncrypted": false
    }
  ]
}

PATCH

Update System Parameter

/api/admin/system-parameters/:paramKey

Update an existing system parameter value or metadata

▼

📋 What This Does:

Updates parameter value or metadata
Supports partial updates (only provided fields)
Can update display name, description, category
Useful for rotating API keys or updating config

📤 Request

URL Parameter: paramKey (required)

All fields in body are optional:

{
  "paramValue": "new-api-key-value",
  "displayName": "Updated Display Name",
  "description": "Updated description",
  "category": "authentication"
}

📥 Response (Success)

{
  "success": true,
  "message": "System parameter updated successfully",
  "data": {
    "id": 123,
    "paramKey": "MONDAY_API_KEY",
    "paramValue": "new-api-key-value",
    "updated_at": "2025-12-29T16:00:00Z"
  }
}

🎨 Connector Management

GET

Get All Connector Templates

/api/v2/admin/connectors

Get all connector templates from all services that have connector configurations

▼

📋 What This Does:

Returns all connector templates from services with connector config
Connector config includes UI metadata (pages, widgets, layouts)
Includes API endpoint mappings to V2 actions
Used by 3rd party applications to build frontends
Enables dynamic UI generation based on backend config

📤 Request

No request body or parameters required

curl -X GET "${baseUrl}/api/v2/admin/connectors"

📥 Response (Success)

{
  "success": true,
  "connectors": [
    {
      "serviceKey": "storm-tracker",
      "connector": {
        "id": "storm-tracker-connector",
        "microservice": "storm-tracker",
        "version": "1.0.0",
        "pages": [
          {
            "page_id": "storms-list",
            "title": "Active Storms",
            "route": "/storms",
            "layout": "list_view",
            "widgets": [...]
          }
        ],
        "api_endpoints": [
          {
            "id": "list-storms",
            "path": "/api/storms",
            "method": "GET",
            "v2_mapping": {
              "service_key": "storm-tracker",
              "action_name": "list-storms"
            }
          }
        ]
      }
    }
  ]
}

💡 Tip: Connector templates are stored in service_definitions.metadata.connector (JSONB). Only services with connector config will appear in the response.

🤖 AI Generation

POST

AI Generate Service

/api/v2/admin/services/generate-from-ai

Use Claude AI to generate a V2 service template from code files, cURL commands, or descriptions

▼

📋 What This Does:

Uses Claude AI to generate V2 service templates
Accepts code files, cURL commands, or descriptions
Generates complete service definitions with actions
Creates api_flow steps automatically
Includes payload schemas and response schemas
Ready to upload and use immediately

📤 Request

Request Body Options:

codeFiles - Array of code file contents
curlCommands - Array of cURL command strings
description - Natural language description

{
  "description": "Create a service for managing user profiles with CRUD operations",
  "codeFiles": [
    {
      "filename": "user-service.js",
      "content": "async function createUser(userData) { ... }"
    }
  ],
  "curlCommands": [
    "curl -X POST https://api.example.com/users -H 'Content-Type: application/json' -d '{\"name\": \"John\"}'"
  ]
}

📥 Response (Success)

{
  "success": true,
  "message": "Service template generated successfully",
  "template": {
    "service": {
      "key": "user-service",
      "name": "User Service",
      "description": "User profile management service",
      "version": "1.0.0"
    },
    "actions": [
      {
        "name": "create-user",
        "displayName": "Create User",
        "api_flow": [...]
      }
    ]
  },
  "usage": {
    "uploadEndpoint": "/api/v2/admin/services/upload",
    "instructions": "Upload the generated template to create the service"
  }
}

💡 Tip: Provide as much context as possible (code, examples, descriptions) for better AI-generated templates. Review and test the generated template before deploying.

📋 API Information

Base URL: Loading...
Total Endpoints: 11 core management APIs Active
Service Management: Create, upload, list, get actions, delete services Active
Action Management: Create, update, delete, enable, disable, and archive actions Active
System Parameters: Create, list, and update API keys, secrets, configuration Active
Connector Management: Get all connector templates from services Active
AI Generation: Generate V2 templates using Claude AI Active

🚀 API Endpoints

📦 Service Management

Create Service

Upload Service Template

📤 Request

📥 Response (Success)

List All Services

📤 Request

📥 Response (Success)

Get Service Actions

📤 Request

📥 Response (Success)

Delete Service

📤 Request

📥 Response (Success)

⚡ Action Management

Create Action

Create Simple Action (Direct Execution)

📤 Request

📥 Response (Success)

🔄 Execution Flow

Manage Action

Request Body Schema

Response Schema

Update Fields (all optional - only provided fields will be updated)

🔐 System Parameters

Create System Parameter

📤 Request

📥 Response (Success)

List System Parameters

📤 Request

📥 Response (Success)

Update System Parameter

📤 Request

📥 Response (Success)

🎨 Connector Management

Get All Connector Templates

📤 Request

📥 Response (Success)

🤖 AI Generation

AI Generate Service

📤 Request

📥 Response (Success)

📋 API Information