PUT

The PUT keyword sends HTTP PUT requests to external APIs, used for replacing or updating entire resources.

Syntax

result = PUT url, data
PUT url WITH field1 = value1, field2 = value2

Parameters

Description

PUT sends data to a specified URL using the HTTP PUT method. In REST APIs, PUT is used to:

• Replace an entire resource with new data
• Create a resource at a specific URL if it doesn’t exist
• Update all fields of an existing resource

Unlike PATCH which updates partial data, PUT typically replaces the entire resource.

Examples

Basic PUT Request

' Update entire user profile
result = PUT "https://api.example.com/users/123" WITH
    name = "John Doe",
    email = "john.doe@example.com",
    phone = "+1-555-0100",
    status = "active"

IF result.success THEN
    TALK "Profile updated successfully!"
ELSE
    TALK "Update failed: " + result.error
END IF

Replace Configuration

' Replace entire configuration object
result = PUT "https://api.example.com/config/bot-settings" WITH
    theme = "dark",
    language = "en",
    notifications = true,
    auto_reply = false

TALK "Configuration saved"

Update Product

' Replace product details
result = PUT "https://api.store.com/products/SKU-001" WITH
    name = "Premium Widget",
    price = 49.99,
    stock = 100,
    category = "electronics",
    description = "High-quality widget with premium features"

TALK "Product updated: " + result.name

With Authentication

' Set authorization header first
SET HEADER "Authorization", "Bearer " + api_token
SET HEADER "Content-Type", "application/json"

' Make authenticated PUT request
result = PUT "https://api.service.com/resources/456" WITH
    title = "Updated Title",
    content = new_content,
    updated_by = user.id

' Clear headers after request
SET HEADER "Authorization", ""

Using JSON String

' PUT with JSON string body
json_body = '{"name": "Updated Name", "status": "published"}'
result = PUT "https://api.example.com/articles/789", json_body

TALK "Article updated!"

PUT vs PATCH vs POST

' POST - Create new
result = POST "https://api.example.com/users" WITH
    name = "New User",
    email = "new@example.com"
' Creates user, returns new ID

' PUT - Replace entire resource
result = PUT "https://api.example.com/users/123" WITH
    name = "Updated Name",
    email = "updated@example.com",
    phone = "+1-555-0100"
' All fields required, replaces entire user

' PATCH - Update specific fields
result = PATCH "https://api.example.com/users/123" WITH
    phone = "+1-555-0200"
' Only phone is updated, other fields unchanged

Common Use Cases

Update User Settings

' Save all user preferences
result = PUT "https://api.example.com/users/" + user.id + "/settings" WITH
    email_notifications = true,
    sms_notifications = false,
    timezone = "America/New_York",
    language = "en"

TALK "Your settings have been saved!"

Replace Document

' Upload new version of document (replaces existing)
document_content = READ "templates/contract.md"

result = PUT "https://api.docs.com/documents/" + doc_id WITH
    title = "Service Agreement v2.0",
    content = document_content,
    version = "2.0",
    last_modified = FORMAT(NOW(), "ISO8601")

TALK "Document replaced with new version"

Update Order Status

' Replace order with updated status
result = PUT "https://api.orders.com/orders/" + order_id WITH
    customer_id = order.customer_id,
    items = order.items,
    total = order.total,
    status = "shipped",
    tracking_number = tracking_id,
    shipped_at = FORMAT(NOW(), "ISO8601")

TALK "Order marked as shipped!"

Error Handling

ON ERROR RESUME NEXT

result = PUT "https://api.example.com/resource/123" WITH
    field1 = value1,
    field2 = value2

IF ERROR THEN
    PRINT "PUT request failed: " + ERROR_MESSAGE
    TALK "Sorry, I couldn't update that information."
ELSE IF result.error THEN
    TALK "Update failed: " + result.error.message
ELSE
    TALK "Update successful!"
END IF

Common HTTP Status Codes

Configuration

Configure HTTP settings in config.csv:

name,value
http-timeout,30
http-retry-count,3
http-retry-delay,1000

Implementation Notes

• Implemented in Rust under src/web_automation/http.rs
• Automatically serializes WITH clause to JSON
• Supports custom headers via SET HEADER
• Returns parsed JSON response
• Handles redirects (up to 10 hops)

Related Keywords

• GET — Retrieve data from URLs
• POST — Create new resources
• PATCH — Partial resource updates
• DELETE HTTP — Remove resources
• SET HEADER — Set request headers

Summary

PUT replaces entire resources via HTTP PUT requests. Use it when you need to update all fields of a resource or create a resource at a specific URL. For partial updates where you only change specific fields, use PATCH instead. Always include all required fields when using PUT, as missing fields may be set to null or cause errors.