chore: import upstream snapshot with attribution

apps/opik-documentation/documentation/fern/docs/reference/python-sdk/rest-api.mdx

@@ -0,0 +1,212 @@
+---
+headline: REST API Client | Opik Documentation
+og:description: Access all Opik platform functionality with the Python SDK's REST
+  API client for advanced operations and custom integrations.
+og:site_name: Opik Documentation
+og:title: REST API Client - Opik Python SDK
+title: REST API Client
+canonical-url: https://www.comet.com/docs/opik/reference/python-sdk/rest-api
+---
+
+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.
+
+<Warning>
+  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.
+</Warning>
+
+## Accessing the REST Client
+
+The REST client is accessible through any Opik instance:
+
+```python
+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
+
+```python
+# 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
+
+```python
+# 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",
+    project_name="my-project"
+)
+
+# 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
+
+```python
+# 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:
+
+```python
+# 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:
+
+```python
+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](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/overview.html).
+
+The reference documentation includes:
+
+- **[Overview & Getting Started](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/overview.html)** - Detailed usage patterns and examples
+- **[API Clients](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/clients/index.html)** - Complete method reference for all clients
+- **[Data Types](https://www.comet.com/docs/opik/python-sdk-reference/rest_api/objects.html)** - Response models and data structures
+
+## 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