Skip to main content
ServFlow supports a code-first workflow where you define APIs directly in YAML configuration files. This approach is ideal for developers who prefer text editors, need version control for their API definitions, or want to integrate with CI/CD pipelines.
Prefer a visual interface? See the Dashboard Quickstart to build APIs using the web UI.

​
Prerequisites

Before starting, ensure you have:
  • ServFlow Pro installed (Installation Guide)
  • A text editor
  • A terminal or command-line interface

​
What You’ll Build

By the end of this tutorial, you’ll have a working “Hello World” API endpoint defined entirely in YAML, running without the dashboard UI.

​
Step 1: Create Your Project Structure

Create a directory for your ServFlow project and the required folders: 
mkdir my-servflow-project
cd my-servflow-project
mkdir configs
The configs directory will hold your API configuration files.

​
Step 2: Create the TOML Configuration

Create a config.toml file in your project root: 
[server]
port = "8080"
config_folder = "./configs"
env = "development"
This minimal configuration tells ServFlow:
  • Listen for API requests on port 8080
  • Load API definitions from the ./configs folder
The config_folder is the only required setting. ServFlow uses sensible defaults for everything else.

​
Step 3: Create Your First API Configuration

Create a file named hello-world.yaml in the configs directory: 
http:
  method: GET
  listen_path: /hello-world

responses:
  success:
    status_code: 200
    body:
      message: "Hello, World!"
      status: "success"

entry: response.success
This YAML configuration defines:
FieldDescription
http.methodThe HTTP method this endpoint accepts (GET)
http.listen_pathThe URL path to listen on (/hello-world)
responses.successA response definition with status code and body
entryWhere the workflow starts — directly returning the success response

​
Step 4: Start ServFlow in Headless Mode

Run ServFlow without the --dashboard flag: 
servflow-pro start --config config.toml
You should see output indicating the server has started: 
INFO    Starting ServFlow Pro    {"config_folder": "./configs", "port": "8080", "dashboard": false}
Without --dashboard, ServFlow runs in headless mode — it serves your APIs but doesn’t start the web UI. This is the recommended mode for production deployments.

​
Step 5: Test Your API

Open a new terminal and test your endpoint: 
curl http://localhost:8080/hello-world
You should receive: 
{
  "message": "Hello, World!",
  "status": "success"
}
Congratulations! You’ve created your first API using YAML configuration.

​
Adding Actions to Your Workflow

Most APIs need to do more than return static responses. Here’s an expanded example that demonstrates actions: 
http:
  method: GET
  listen_path: /greeting
  query_params:
    - name

actions:
  build_greeting:
    type: static
    config:
      value:
        greeting: "Hello, {{ param \"name\" }}!"
        timestamp: "{{ now }}"
    next: response.success

responses:
  success:
    status_code: 200
    body: "{{ .build_greeting }}"

entry: action.build_greeting
This configuration:
  1. Accepts a name query parameter
  2. Uses a static action to build a dynamic response
  3. Returns the greeting with the current timestamp
Test it with: 
curl "http://localhost:8080/greeting?name=Developer"

​
YAML Configuration Structure

Every API configuration file follows this structure: 
# Entry point definition (HTTP or MCP)
http:
  method: GET|POST|PUT|DELETE|PATCH
  listen_path: /your-path
  query_params: []    # Optional
  headers: []         # Optional

# Actions perform operations
actions:
  action_id:
    type: action_type
    config:
      # Type-specific configuration
    next: action.next_step    # On success
    fail: response.error      # On failure

# Conditional branching
conditionals:
  condition_id:
    expression: "{{ expression }}"
    if_true: action.do_something
    if_false: response.not_found

# Response definitions
responses:
  response_id:
    status_code: 200
    body:
      # Response body

# Where the workflow begins
entry: action.first_step
See the Actions Reference for all available action types and their configurations.

​
Hot Reloading

ServFlow automatically detects changes to YAML files in your config_folder. When you save a file:
  • New configurations are loaded immediately
  • Modified configurations are updated
  • Deleted files remove the corresponding endpoints
No server restart required during development.

​
Version Control Best Practices

Since your APIs are defined in YAML files, you can:
  • Track changes with Git or other version control systems
  • Review API changes through pull requests
  • Deploy consistently across environments using the same configuration files
  • Roll back to previous versions if issues arise
Example .gitignore for a ServFlow project: 
# ServFlow data
data/
*.db

# Environment-specific config
config.toml

# Keep configs in version control
!configs/

​
Next Steps

Running Modes

Understand when to use headless mode vs. dashboard mode.

Actions Reference

Explore all available actions for your workflows.

Dynamic Content

Learn template syntax for dynamic values in your YAML.

Configuration Reference

Explore all TOML configuration options.