Update Loop - Human in the Loop

Update the details of an existing loop. You can modify the name, description, and icon of any loop you’ve created. This operation preserves all members and existing requests.

Authentication

Authorization

string

required

Your API key for authentication

Path Parameters

string

required

The unique identifier of the loop to update

Body Parameters

name

string

New name for the loop (1-100 characters)

description

string

New description of the loop’s purpose (max 500 characters)

icon

string

New icon identifier for the loop

All body parameters are optional. Only provide the fields you want to update.

Response

error

boolean

Whether an error occurred

msg

string

Success message

data

object

Show data

loop

object

The updated loop object with all current information

Show loop

string

Unique identifier for the loop

name

string

Updated name of the loop

description

string

Updated description of the loop

icon

string

Updated icon identifier

creator_id

string

ID of the loop creator (unchanged)

members

array

Array of loop members (unchanged)

member_count

integer

Total number of members

pending_count

integer

Number of pending invitations

created_at

string

ISO timestamp of creation (unchanged)

updated_at

string

ISO timestamp of this update

curl -X PUT https://api.hitl.sh/v1/api/loops/65f1234567890abcdef12345 \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Content Moderation",
    "description": "Advanced review system for user-generated content with improved guidelines",
    "icon": "shield-exclamation"
  }'

{
  "error": false,
  "msg": "Loop updated successfully",
  "data": {
    "loop": {
      "id": "65f1234567890abcdef12345",
      "name": "Enhanced Content Moderation",
      "description": "Advanced review system for user-generated content with improved guidelines",
      "icon": "shield-exclamation",
      "creator_id": "65f1234567890abcdef12346",
      "members": [
        {
          "user_id": "65f1234567890abcdef12346",
          "email": "creator@example.com",
          "status": "active",
          "joined_at": "2024-03-15T10:30:00Z"
        },
        {
          "user_id": "65f1234567890abcdef12347",
          "email": "reviewer1@example.com",
          "status": "active", 
          "joined_at": "2024-03-15T11:45:00Z"
        }
      ],
      "member_count": 2,
      "pending_count": 0,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T14:20:00Z"
    }
  }
}

Update Scenarios

Name Only Update

Update just the loop name:

{
  "name": "Content Review V2"
}

Description Only Update

Update just the description:

{
  "description": "Updated workflow for reviewing user submissions with new compliance requirements"
}

Icon Only Update

Update just the icon:

{
  "icon": "shield-alt"
}

Partial Update

Update multiple fields (but not all):

{
  "name": "Premium Content Review",
  "icon": "star"
}

Available Icons

Security

shield-check, shield-alt, shield-exclamation, lock, key

Content

document-text, document-check, file-text, clipboard, edit

Review

eye, search, thumbs-up, thumbs-down, star

Quality

badge-check, certificate, award, beaker, cog

Communication

chat, comment, bell, megaphone, mail

General

folder, tag, flag, bookmark, heart

Validation Rules

Name Validation

Required: No (optional for updates)
Min length: 1 character
Max length: 100 characters
Allowed: Letters, numbers, spaces, and basic punctuation

Description Validation

Required: No (optional for updates)
Max length: 500 characters
Allowed: All characters including newlines

Icon Validation

Required: No (optional for updates)
Format: String identifier
Validation: Must be a valid icon identifier from available icons

Use Cases

Rebranding Loops

Update loop name and icon for rebranding:

def rebrand_loop(loop_id, new_name, new_icon):
    url = f"https://api.hitl.sh/v1/api/loops/{loop_id}"
    data = {
        "name": new_name,
        "icon": new_icon
    }
    
    response = requests.put(url, headers=headers, json=data)
    
    if response.status_code == 200:
        loop_data = response.json()["data"]["loop"]
        print(f"Successfully rebranded loop to '{loop_data['name']}'")
        return loop_data
    else:
        print(f"Failed to rebrand loop: {response.json()['msg']}")
        return None

Improving Descriptions

Add more detailed descriptions to existing loops:

async function improveLoopDescription(loopId, newDescription) {
    try {
        const response = await axios.put(
            `https://api.hitl.sh/v1/api/loops/${loopId}`,
            { description: newDescription },
            { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }
        );
        
        console.log('Description updated successfully');
        return response.data.data.loop;
    } catch (error) {
        console.error('Failed to update description:', error.response?.data?.msg);
        throw error;
    }
}

// Usage
await improveLoopDescription(
    'loopId',
    'Comprehensive content moderation with AI pre-filtering and human oversight for policy violations'
);

Bulk Loop Updates

Update multiple loops with a consistent naming scheme:

def standardize_loop_names(loop_prefix="Review"):
    # Get all loops
    loops_response = requests.get("https://api.hitl.sh/v1/api/loops", headers=headers)
    loops = loops_response.json()["data"]["loops"]
    
    updated_loops = []
    for loop in loops:
        # Skip loops that already follow the naming convention
        if loop["name"].startswith(loop_prefix):
            continue
            
        new_name = f"{loop_prefix} - {loop['name']}"
        
        update_response = requests.put(
            f"https://api.hitl.sh/v1/api/loops/{loop['id']}", 
            headers=headers, 
            json={"name": new_name}
        )
        
        if update_response.status_code == 200:
            updated_loops.append(update_response.json()["data"]["loop"])
    
    return updated_loops

Access Control

Who Can Update Loops

Loop Creators

Only the user who created the loop can update it. This is enforced by checking the creator_id against the authenticated user.

API Key Restrictions

API keys can only update loops created by the same user account that owns the API key.

Loop Members

Regular loop members cannot update loop details. They can only participate in reviews.

Error Handling

Common Error Scenarios

Loop Not Found

{
  "error": true,
  "msg": "Loop not found"
}

Causes:

Invalid loop ID
Loop was deleted
User doesn’t own the loop

Access Denied

{
  "error": true,
  "msg": "Access denied to this loop"
}

Cause: Only loop creators can update loops.

Validation Error

{
  "error": true,
  "msg": "Validation failed",
  "data": "name must be between 1 and 100 characters"
}

Causes:

Name too long (>100 characters)
Name empty (if provided)
Description too long (>500 characters)
Invalid icon identifier

Empty Update

{
  "error": true,
  "msg": "At least one field must be provided for update"
}

Cause: Request body is empty or contains no valid update fields.

Best Practices

Versioning Updates

Track major changes with version numbers in names:

def version_loop_update(loop_id, updates, version=None):
    if version:
        if 'name' in updates:
            updates['name'] = f"{updates['name']} v{version}"
        updates['description'] = f"{updates.get('description', '')} (Updated to v{version})"
    
    return requests.put(f"https://api.hitl.sh/v1/api/loops/{loop_id}", headers=headers, json=updates)

Gradual Updates

Update loops incrementally rather than all at once:

async function updateLoopGradually(loopId, updates) {
    const updateOrder = ['description', 'icon', 'name']; // Update description first, name last
    
    for (const field of updateOrder) {
        if (updates[field]) {
            await axios.put(
                `https://api.hitl.sh/v1/api/loops/${loopId}`,
                { [field]: updates[field] },
                { headers: { 'Authorization': `Bearer ${apiKey}` } }
            );
            
            // Small delay between updates
            await new Promise(resolve => setTimeout(resolve, 100));
        }
    }
}

Backup Before Updates

Keep a record of previous state:

def safe_loop_update(loop_id, updates):
    # Get current state
    current_response = requests.get(f"https://api.hitl.sh/v1/api/loops/{loop_id}", headers=headers)
    backup = current_response.json()["data"]["loop"]
    
    # Perform update
    update_response = requests.put(
        f"https://api.hitl.sh/v1/api/loops/{loop_id}", 
        headers=headers, 
        json=updates
    )
    
    if update_response.status_code == 200:
        return {
            "success": True,
            "updated": update_response.json()["data"]["loop"],
            "backup": backup
        }
    else:
        return {
            "success": False,
            "error": update_response.json()["msg"],
            "backup": backup
        }

Next Steps

Delete Loop

Learn how to delete loops when they’re no longer needed.

Manage Members

Add or remove members from your updated loop.

View Loop Requests

See all requests that have been created within this loop.

Getting Started

Loops

Requests

Webhooks

Documentation Index

​Authentication

​Path Parameters

​Body Parameters

​Response

​Update Scenarios

​Name Only Update

​Description Only Update

​Icon Only Update

​Partial Update

​Available Icons

Security

Content

Review

Quality

Communication

General

​Validation Rules

​Name Validation

​Description Validation

​Icon Validation

​Use Cases

​Rebranding Loops

​Improving Descriptions

​Bulk Loop Updates

​Access Control

​Who Can Update Loops

​Error Handling

​Common Error Scenarios

​Best Practices

​Versioning Updates

​Gradual Updates

​Backup Before Updates

​Next Steps

Delete Loop

Manage Members

View Loop Requests

Authentication

Path Parameters

Body Parameters

Response

Update Scenarios

Name Only Update

Description Only Update

Icon Only Update

Partial Update

Available Icons

Validation Rules

Name Validation

Description Validation

Icon Validation

Use Cases

Rebranding Loops

Improving Descriptions

Bulk Loop Updates

Access Control

Who Can Update Loops

Error Handling

Common Error Scenarios

Best Practices

Versioning Updates

Gradual Updates

Backup Before Updates

Next Steps