Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.byteful.com/llms.txt

Use this file to discover all available pages before exploring further.

Metadata provides a flexible way to store additional information with your resources. The Byteful API supports metadata on several resources, allowing you to add custom attributes without changing the core API structure. Metadata is particularly useful for resellers who want to store information about their customers on our systems, or users who want to label or add information to specific proxy users or services.

​
Supported Resources with Metadata

The following resources support metadata fields:
  • Proxy Users (proxy_user_metadata)
  • Services (service_metadata)

​
Metadata Structure

Metadata is stored as a JSON object with key-value pairs. For example: 
{
  "customer_reference_id": "CR-12345",
  "department": "Marketing",
  "project": "Q2 Campaign",
  "is_priority": true,
  "employee_id": 1500
}

​
Supported Value Types

Metadata supports the following value types:
  • String: Text values (e.g., "department": "Marketing")
  • Integer: Whole numbers (e.g., "employee_id": 1500)
  • Float: Decimal numbers (e.g., "success_rate": 98.6)
  • Boolean: True/false values (e.g., "is_priority": true)
To store datetime objects, we recommend using timestamps as integers since they’re more efficiently stored and queried. They can also be compared using the min_ and max_ operators.

​
Constraints

When working with metadata in the Byteful API, keep these constraints in mind:
  • Non-nested structure: Metadata must be a flat JSON object (no nested objects)
  • Limited keys: Maximum of 30 keys per metadata object
  • Value length: Each value’s string representation must be ≤ 300 characters
  • Size limit: Total metadata size must be ≤ 32KB
  • Supported value types: String, boolean, float, and integer values

​
Adding Metadata

You can add metadata when creating or updating resources. For example, when creating a proxy user: 
{
  "proxy_user_id": "stevejobs",
  "proxy_user_metadata": {
    "department": "Marketing",
    "cost_center": "CC-45678",
    "manager": "Jane Smith"
  }
}

​
Updating Metadata

When updating metadata, you must provide the complete metadata object. The API will replace the existing metadata with your new object, not merge them. For example, to update a service’s metadata: 
{
  "service_metadata": {
    "project": "Updated Project Name",
    "department": "Sales",
    "priority": "high"
  }
}

​
Searching by Metadata

The API allows filtering resources based on their metadata values. This is particularly powerful for organizing and retrieving resources based on your custom attributes.

​
Metadata Search Operators

When searching, you can use the following formats:
  • Exact match: proxy_user_metadata.department=Marketing
  • Minimum value: proxy_user_metadata.min_employee_id=1000
  • Maximum value: proxy_user_metadata.max_employee_id=2000
  • Contains substring: proxy_user_metadata.like_project=%Campaign%
  • Not equal: proxy_user_metadata.not_department=IT
  • Existence check:
    • proxy_user_metadata.exists_project=true (key must exist)
    • proxy_user_metadata.exists_project=false (key must not exist)

​
Code Examples

# Creating a proxy user with metadata
curl --request POST \
  --url 'https://api.byteful.com/1.0/public/user/proxy_user/create' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key' \
  --data '{
    "proxy_user_id": "john_marketing",
    "proxy_user_metadata": {
      "department": "Marketing",
      "cost_center": "CC-45678",
      "project": "Summer Campaign",
      "is_priority": true,
      "employee_id": 1500
    }
  }'

# Updating a service's metadata
curl --request POST \
  --url 'https://api.byteful.com/1.0/public/user/service/update' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key' \
  --data '{
    "service_id": "srv-12345",
    "service_metadata": {
      "project": "Fall Campaign",
      "department": "Sales",
      "priority": "high"
    }
  }'

# Searching for proxy users in the Marketing department
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/proxy_user/search?proxy_user_metadata.department=Marketing' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

# Searching for high-priority services
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/service/search?proxy_user_metadata.priority=high' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

​
Example Use Cases

  • Reseller customer tracking: Store client-specific identifiers and attributes
  • Client organization: Track which client or project a resource belongs to
  • Custom grouping: Create your own grouping scheme beyond the API’s built-in categories
  • Usage tracking: Add purpose or usage details to track resource utilization
By effectively using metadata, you can extend the Byteful API to fit your organization’s specific needs and workflows.