Skip to content

rest-api.mdx

Latest commit

 

History

History
205 lines (156 loc) · 6.24 KB

rest-api.mdx

File metadata and controls

205 lines (156 loc) · 6.24 KB
title
REST API Client

The Opik Python SDK includes a complete REST API client that provides direct access to all Opik platform functionality. This low-level client is available through the rest_client property and is useful for advanced operations, custom integrations, and scenarios where the high-level SDK doesn't provide the needed functionality.

The REST client is not guaranteed to be backward compatible with future SDK versions. While it provides convenient access to the current REST API, it's not considered safe to heavily rely on its API as Opik's REST API contracts may change.

Accessing the REST Client

The REST client is accessible through any Opik instance:

import opik

# Initialize Opik client
client = opik.Opik()

# Access the REST API client
rest_client = client.rest_client

# Now you can use any of the available client methods
traces = rest_client.traces.search_traces(project_name="my-project")

Available Clients

The REST API is organized into functional client modules:

Core Resources

  • traces - Manage traces and their lifecycle
  • spans - Manage spans within traces
  • datasets - Manage datasets and dataset items
  • experiments - Manage experiments and results
  • projects - Manage projects and project settings

Feedback & Evaluation

  • feedback_definitions - Define feedback score types
  • automation_rule_evaluators - Set up automated evaluation rules
  • optimizations - Run optimization experiments

Content & Assets

  • prompts - Manage prompt templates and versions
  • attachments - Handle file attachments for traces and spans

System & Configuration

  • check - System health and access verification
  • workspaces - Workspace management
  • llm_provider_key - API key management for LLM providers
  • service_toggles - Feature flag management
  • system_usage - Usage metrics and monitoring

Integrations

  • chat_completions - Chat completion endpoints
  • open_telemetry_ingestion - OpenTelemetry data ingestion
  • guardrails - Content validation and safety checks

Common Usage Patterns

Working with Traces

# Get a specific trace by ID
trace = client.rest_client.traces.get_trace_by_id("trace-id")

# Search traces with advanced filters
traces = client.rest_client.traces.search_traces(
    project_name="my-project",
    filters=[{
        "field": "name",
        "operator": "contains",
        "value": "important"
    }],
    max_results=100
)

# Add feedback to a trace
client.rest_client.traces.add_trace_feedback_score(
    id="trace-id",
    name="accuracy",
    value=0.95,
    source="manual"
)

Managing Datasets

# List all datasets with pagination
datasets = client.rest_client.datasets.find_datasets(
    page=0,
    size=20
)

# Create a new dataset
dataset = client.rest_client.datasets.create_dataset(
    name="evaluation-dataset",
    description="Dataset for model evaluation"
)

# Add items to the dataset
items = [
    {
        "input": {"question": "What is machine learning?"},
        "expected_output": {"answer": "A subset of AI..."}
    }
]
client.rest_client.datasets.create_or_update_dataset_items(
    dataset_id=dataset.id,
    items=items
)

Running Experiments

# Create an experiment linked to a dataset
experiment = client.rest_client.experiments.create_experiment(
    name="model-comparison",
    dataset_name="evaluation-dataset"
)

# Add experiment results
client.rest_client.experiments.create_experiment_items(
    experiment_id=experiment.id,
    items=[{
        "dataset_item_id": "item-id",
        "trace_id": "trace-id",
        "output": {"prediction": "model output"},
        "feedback_scores": [
            {"name": "accuracy", "value": 0.8}
        ]
    }]
)

Response Types and Pagination

Most list operations return paginated responses with a consistent structure:

# Example paginated response
response = client.rest_client.datasets.find_datasets(page=0, size=10)

# Access the response data
datasets = response.content    # List of dataset objects
total_count = response.total   # Total number of items
current_page = response.page   # Current page number
page_size = response.size      # Items per page

Error Handling

The REST API raises specific exceptions for different error conditions:

from opik.rest_api.core.api_error import ApiError

try:
    trace = client.rest_client.traces.get_trace_by_id("invalid-id")
except ApiError as e:
    if e.status_code == 404:
        print("Trace not found")
    elif e.status_code == 403:
        print("Access denied")
    else:
        print(f"API error: {e.status_code} - {e.body}")

When to Use the REST API

Consider using the REST API client when you need to:

  • Advanced Filtering: Complex search operations with multiple filters
  • Batch Operations: Process large amounts of data efficiently
  • Custom Integrations: Build tools that integrate with external systems
  • Raw Data Access: Work directly with API responses for specific use cases
  • Unsupported Operations: Access functionality not available in the high-level SDK

Complete API Reference

For comprehensive documentation of all REST API methods, parameters, and response types, see the complete REST API Reference.

The reference documentation includes:

Best Practices

  1. Use High-Level SDK First: Try the main SDK APIs before resorting to REST client
  2. Handle Pagination: Always implement proper pagination for list operations
  3. Error Handling: Implement robust error handling for network and API errors
  4. Rate Limiting: Be mindful of API rate limits for batch operations
  5. Version Compatibility: Test thoroughly when upgrading SDK versions