Payloads - Triform

What is a Payload?

A Payload is the input data you provide when executing a Project, Flow, Agent, or Action. It’s a JSON object that contains all the information needed for that execution. Think of it as:

The arguments to a function
The request body of an API call
The input to your system

Why Payloads

Speed — One‑click reruns for common cases.
Reproducibility — Lock in known‑good inputs as your baseline.
Documentation — Show how a component is intended to be used.

Good Payloads include

Minimal required fields with realistic values.
Edge‑case variants (empty, large, malformed types).
Comments or README references for context.

Workflow

Create a Payload for a Node (Action/Flow).
Refine the Node until the output is acceptable.
Keep the Payload as a regression check when you iterate.

tip: Name by intent — Prefer names like minimal, typical_customer, edge_empty_messages over test1, test2.

Payload structure

Basic payload

{
  "field1": "value",
  "field2": 123,
  "field3": true
}

Nested payload

{
  "user": {
    "id": "user_123",
    "email": "alice@example.com",
    "tier": "premium"
  },
  "action": "process_order",
  "items": [
    {"id": "item_1", "quantity": 2},
    {"id": "item_2", "quantity": 1}
  ]
}

Payload with metadata

{
  "data": {
    "user_input": "Summarize this article..."
  },
  "config": {
    "format": "bullets",
    "max_length": 200
  },
  "metadata": {
    "request_id": "req_xyz",
    "source": "web_app"
  }
}

Payload schema

The schema defines what fields are expected, their types, and validation rules.

Defining a schema

In your Project/Flow Input node:

{
  "user_id": {
    "type": "string",
    "required": true,
    "description": "Unique user identifier"
  },
  "action": {
    "type": "enum",
    "options": ["create", "update", "delete"],
    "required": true,
    "description": "Operation to perform"
  },
  "data": {
    "type": "object",
    "required": false,
    "description": "Operation-specific data"
  },
  "options": {
    "type": "object",
    "required": false,
    "default": {},
    "description": "Optional configuration"
  }
}

Data types

Type	Example	Description
`string`	`"hello"`	Text
`number`	`42`, `3.14`	Integer or float
`boolean`	`true`, `false`	True/false
`array`	`[1, 2, 3]`	List of items
`object`	`{"key": "value"}`	Nested structure
`enum`	`"red"` from `["red", "green", "blue"]`	Fixed options
`null`	`null`	Absence of value

Required vs. optional

Required fields:

Must be present in every payload
Execution fails if missing
No default value

Optional fields:

Can be omitted
Can have default values
Execution continues without them

Example:

{
  "required_field": "must be here",
  "optional_field": "can be omitted"
}

Creating payloads

In the UI

Select your Project/Flow/Agent
Go to Properties → Execute
Enter payload in the JSON editor
Click Execute

Tips:

Use the schema viewer to see expected fields
Auto-complete helps with field names
Syntax highlighting catches errors

Via API

curl -X POST https://api.triform.ai/v1/your-project/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123",
    "action": "process",
    "data": {"value": 42}
  }'

Programmatically

Python:

import requests

payload = {
    "user_id": "123",
    "action": "process",
    "data": {"value": 42}
}

response = requests.post(
    "https://api.triform.ai/v1/your-project/execute",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json=payload
)

result = response.json()

JavaScript:

const payload = {
  user_id: "123",
  action: "process",
  data: { value: 42 }
};

const response = await fetch(
  "https://api.triform.ai/v1/your-project/execute",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const result = await response.json();

Payload validation

Triform validates payloads against the schema before execution.

Common validation errors

Missing required field:

{
  "error": "ValidationError",
  "message": "Missing required field: user_id",
  "field": "user_id"
}

Wrong type:

{
  "error": "ValidationError",
  "message": "Expected number but got string",
  "field": "age",
  "expected": "number",
  "actual": "string"
}

Invalid enum value:

{
  "error": "ValidationError",
  "message": "Invalid value for action. Must be one of: create, update, delete",
  "field": "action",
  "value": "invalid_action",
  "allowed": ["create", "update", "delete"]
}

Out of range:

{
  "error": "ValidationError",
  "message": "Value must be between 0 and 100",
  "field": "percentage",
  "value": 150,
  "min": 0,
  "max": 100
}

Saved payloads

Save frequently-used payloads for quick testing.

Saving a payload

Enter payload in Execute panel
Click Save Payload
Name it: Test Case 1: Happy Path
Click Save

Loading a saved payload

Go to Execute panel
Click Load Payload
Select from list
Click Load
Optionally modify
Execute

Payload library

Organize saved payloads: By category:

Happy path examples
Edge cases
Error scenarios
Performance tests
Regression tests

By purpose:

demo_payload — For demonstrations
test_minimal — Minimum required fields
test_full — All fields populated
test_edge_empty_list — Edge case testing

Payload best practices

Provide examples — Include sample payloads in documentation

Use meaningful values — "user_123" is better than "test"

Test edge cases — Empty arrays, null values, max sizes

Save regression tests — Keep payloads that found bugs

Document schema — Clear descriptions for each field

Version payloads — If schema changes, update saved payloads

Payload patterns

Pattern 1: Simple request

{
  "input": "string to process"
}

Use case: Single-purpose operations (text summarization, translation)

Pattern 2: User + action + data

{
  "user_id": "123",
  "action": "create",
  "data": {
    "name": "New Item",
    "description": "Item details"
  }
}

Use case: CRUD operations, user-specific actions

Pattern 3: Batch processing

{
  "items": [
    {"id": "1", "value": "A"},
    {"id": "2", "value": "B"},
    {"id": "3", "value": "C"}
  ],
  "options": {
    "parallel": true,
    "fail_fast": false
  }
}

Use case: Processing multiple items, bulk operations

Pattern 4: Configuration-heavy

{
  "data": "content to process",
  "config": {
    "format": "markdown",
    "style": "formal",
    "length": "medium",
    "audience": "technical",
    "include_citations": true
  }
}

Use case: Configurable behavior, user preferences

Pattern 5: Streaming/chunked

{
  "chunk_id": "chunk_1",
  "total_chunks": 10,
  "data": "partial data...",
  "metadata": {
    "session_id": "session_xyz"
  }
}

Use case: Large payloads split into chunks, streaming data

Dynamic payloads

Generate payloads programmatically.

From user input

def create_payload(user_input):
    return {
        "query": user_input,
        "timestamp": datetime.now().isoformat(),
        "user_id": get_current_user_id()
    }

From database

def create_batch_payload(user_ids):
    users = fetch_users(user_ids)
    return {
        "users": [
            {
                "id": u.id,
                "email": u.email,
                "tier": u.tier
            }
            for u in users
        ]
    }

From webhook

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    webhook_data = request.json
    
    payload = {
        "event_type": webhook_data['type'],
        "data": webhook_data['data'],
        "received_at": datetime.now().isoformat()
    }
    
    # Send to Triform
    execute_project(payload)
    
    return {'status': 'received'}

Payload transformation

Sometimes you need to transform external data into Triform payload format.

Example transformation

External API response:

{
  "userId": "123",
  "fullName": "Alice Smith",
  "emailAddress": "alice@example.com",
  "accountLevel": "PREMIUM"
}

Triform payload:

{
  "user_id": "123",
  "name": "Alice Smith",
  "email": "alice@example.com",
  "tier": "premium"
}

Transformation code:

def transform_to_payload(api_response):
    return {
        "user_id": api_response["userId"],
        "name": api_response["fullName"],
        "email": api_response["emailAddress"],
        "tier": api_response["accountLevel"].lower()
    }

Debugging payloads

Common issues

Problem: Execution fails with validation error
Solution: Check payload against schema, fix type mismatches or missing fields Problem: Payload is valid but execution fails
Solution: Check execution logs, data might be valid format but wrong content Problem: Payload too large
Solution: Check quotas, consider chunking or reducing data size Problem: Payload works in UI but not via API
Solution: Check JSON encoding, content-type header, authentication

Testing payloads

Step 1: Start simple

{
  "minimal_required_field": "value"
}

Step 2: Add optional fields

{
  "minimal_required_field": "value",
  "optional_field": "value"
}

Step 3: Add complexity

{
  "minimal_required_field": "value",
  "optional_field": "value",
  "nested_object": {
    "key": "value"
  },
  "array": [1, 2, 3]
}

Step 4: Test edge cases

{
  "empty_string": "",
  "empty_array": [],
  "null_value": null,
  "large_number": 999999999
}

Payload size limits

Default limits

Free tier: 1 MB per payload
Pro tier: 10 MB per payload
Enterprise: Custom limits

Handling large payloads

Option 1: Chunking Split large payloads into smaller chunks, process sequentially Option 2: Reference by URL

{
  "data_url": "https://s3.amazonaws.com/bucket/large-file.json",
  "process_type": "batch"
}

Next steps

Continue exploring the documentation to learn about Executions, Variables, and integrating Projects into your apps.

​What is a Payload?

​Why Payloads

​Good Payloads include

​Workflow

​Payload structure

​Basic payload

​Nested payload

​Payload with metadata

​Payload schema

​Defining a schema

​Data types

​Required vs. optional

​Creating payloads

​In the UI

​Via API

​Programmatically

​Payload validation

​Common validation errors

​Saved payloads

​Saving a payload

​Loading a saved payload

​Payload library

​Payload best practices

​Payload patterns

​Pattern 1: Simple request

​Pattern 2: User + action + data

​Pattern 3: Batch processing

​Pattern 4: Configuration-heavy

​Pattern 5: Streaming/chunked

​Dynamic payloads

​From user input

​From database

​From webhook

​Payload transformation

​Example transformation

​Debugging payloads

​Common issues

​Testing payloads

​Payload size limits

​Default limits

​Handling large payloads

​Next steps