HTTP Write Task
Learn how to send commands to HTTP endpoints with Synnax.
For task lifecycle management, see the Task Basics page.
How Commands Work
HTTP Write Tasks use command channels to send values to HTTP endpoints:
- When a value is written to a command channel, the driver sends an HTTP request to the corresponding endpoint.
- The channel value is placed in the JSON request body at a location specified by a JSON Pointer.
- Each endpoint has exactly one command channel that drives it, plus optional static and generated fields that are included in every request.
Task Configuration Reference
Endpoint Configuration Reference
Each endpoint maps a single Synnax command channel to an HTTP request. When the channel receives a value, the Driver builds the JSON body and sends the request.
Field Types Reference
The request body is constructed from three types of fields, each placed at a JSON Pointer location in the body.
Channel Field (required)
The channel field is the primary field on each endpoint. Its value comes from a Synnax command channel — when a value is written to the channel, the driver places it in the request body at the specified pointer.
http.ChannelField(
pointer="/value",
json_type="number",
channel=setpoint_cmd.key,
) Enum Values
When the HTTP request body should contain string values that represent discrete states,
use enum_values to map them to numbers. The Driver converts matching strings to their
numeric equivalents before writing to the channel.
http.ChannelField(
pointer="/source",
json_type="string",
channel=source_cmd.key,
enum_values=[{"label": "OFF", "value": 0}, {"label": "ON", "value": 1}],
) Generated Fields
Generated fields produce a new value for each request. Two generator types are supported:
# UUID generator - produces a unique ID per request
http.GeneratedField(
pointer="/request_id",
generator="uuid",
)
# Timestamp generator - produces current time per request
http.GeneratedField(
pointer="/timestamp",
generator="timestamp",
time_format="iso8601",
)How-To
Configure and run task
import synnax as sy
from synnax import http
client = sy.Synnax()
# Retrieve the HTTP device
dev = client.devices.retrieve(name="My HTTP Server")
# Create a command time index
http_cmd_time = client.channels.create(
name="http_cmd_time",
is_index=True,
data_type=sy.DataType.TIMESTAMP,
retrieve_if_name_exists=True,
)
# Create a command channel
setpoint_cmd = client.channels.create(
name="http_setpoint_cmd",
index=http_cmd_time.key,
data_type=sy.DataType.FLOAT64,
retrieve_if_name_exists=True,
)
# Create the write task
task = http.WriteTask(
name="HTTP Write Task",
device=dev.key,
endpoints=[
http.WriteEndpoint(
method="PUT",
path="/api/v1/setpoint",
channel=http.ChannelField(
pointer="/value",
json_type="number",
channel=setpoint_cmd.key,
),
),
],
)
# Configure the task with Synnax
client.tasks.configure(task)
# Start task and send commands
with task.run():
with client.open_writer(
start=sy.TimeStamp.now(),
channels=[http_cmd_time.key, setpoint_cmd.key],
enable_auto_commit=True,
) as writer:
writer.write({
http_cmd_time.key: sy.TimeStamp.now(),
setpoint_cmd.key: 42.0,
})
writer.commit() Use static and generated fields
import synnax as sy
from synnax import http
client = sy.Synnax()
dev = client.devices.retrieve(name="My HTTP Server")
http_cmd_time = client.channels.create(
name="http_cmd_time",
is_index=True,
data_type=sy.DataType.TIMESTAMP,
retrieve_if_name_exists=True,
)
setpoint_cmd = client.channels.create(
name="http_setpoint_cmd",
index=http_cmd_time.key,
data_type=sy.DataType.FLOAT64,
retrieve_if_name_exists=True,
)
# Each request body will contain:
# {
# "value": <channel value>,
# "source": "synnax",
# "request_id": "<generated uuid>"
# }
task = http.WriteTask(
name="HTTP Write Task",
device=dev.key,
endpoints=[
http.WriteEndpoint(
method="POST",
path="/api/v1/control",
channel=http.ChannelField(
pointer="/value",
json_type="number",
channel=setpoint_cmd.key,
),
fields=[
http.StaticField(
pointer="/source",
json_type="string",
value="synnax",
),
http.GeneratedField(
pointer="/request_id",
generator="uuid",
),
],
),
],
)
client.tasks.configure(task)