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.

Getting Started

Tutorials

Triton

Workspace

Core Concepts

Organizations

Quotas

Security

Changelog

Roadmap

Support

Appendix

​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