> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudoapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CRUD Operations

> Managing stored chat completions (OpenAI only)

CRUD operations allow you to store, retrieve, update, and delete OpenAI Chat Completions for analysis, caching, and model improvement.

## Storing Completions

### Basic Storage

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  async function basicStorage() {
    try {
      // Create and store a completion
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [
          { role: "user", content: "Explain machine learning" }
        ],
        store: true,  // Enable storage
        metadata: {
          userId: "user_123",
          topic: "education",
          session: "learning_session_1"
        }
      });
      
      const completionId = response.id;
      console.log(`Stored completion with ID: ${completionId}`);
      console.log(`Response: ${response.choices[0].message.content}`);
    } catch (error) {
      console.error("Storage error:", error);
    }
  }

  basicStorage();
  ```

  ```python Python theme={null}
  import os
  from sudo import Sudo

  with Sudo(
      server_url="https://sudoapp.dev/api",
      api_key=os.getenv("SUDO_API_KEY"),
  ) as client:
      # Create and store a completion
      response = client.router.create(
          model="gpt-4o",
          messages=[
              {"role": "user", "content": "Explain machine learning"}
          ],
          store=True,  # Enable storage
          metadata={
              "user_id": "user_123",
              "topic": "education",
              "session": "learning_session_1"
          }
      )
      
      completion_id = response.id
      print(f"Stored completion with ID: {completion_id}")
      print(f"Response: {response.choices[0].message.content}")
  ```
</CodeGroup>

## Retrieving Completions

### List Stored Completions

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  async function listStoredCompletions() {
    try {
      // List all stored completions
      const completions = await sudo.router.listChatCompletions({
        limit: 10,
        order: "desc"  // Most recent first
      });
      
      console.log(`Found ${completions.data.length} stored completions:`);
      completions.data.forEach(completion => {
        console.log(`- ID: ${completion.id}`);
        console.log(`  Model: ${completion.model}`);
        console.log(`  Created: ${completion.created}`);
        if (completion.metadata) {
          console.log(`  Metadata: ${JSON.stringify(completion.metadata)}`);
        }
      });
    } catch (error) {
      console.error("List completions error:", error);
    }
  }

  listStoredCompletions();
  ```

  ```python Python theme={null}
  import os
  from sudo import Sudo

  with Sudo(
      server_url="https://sudoapp.dev/api",
      api_key=os.getenv("SUDO_API_KEY"),
  ) as client:
      # List all stored completions
      completions = client.router.list_chat_completions(
          limit=10,
          order="desc"  # Most recent first
      )
      
      print(f"Found {len(completions.data)} stored completions:")
      for completion in completions.data:
          print(f"- ID: {completion.id}")
          print(f"  Model: {completion.model}")
          print(f"  Created: {completion.created}")
          if completion.metadata:
              print(f"  Metadata: {completion.metadata}")
  ```
</CodeGroup>

### Filter by Metadata

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  async function filterByMetadata() {
    try {
      // Filter completions by metadata
      const completions = await sudo.router.listChatCompletions({
        metadata: {
          userId: "user_123",
          topic: "education"
        },
        limit: 5
      });
      
      console.log("Education-related completions:");
      completions.data.forEach(completion => {
        console.log(`- ${completion.id}: ${completion.model}`);
      });
    } catch (error) {
      console.error("Filter by metadata error:", error);
    }
  }

  filterByMetadata();
  ```

  ```python Python theme={null}
  import os
  from sudo import Sudo

  with Sudo(
      server_url="https://sudoapp.dev/api",
      api_key=os.getenv("SUDO_API_KEY"),
  ) as client:
      # Filter completions by metadata
      completions = client.router.list_chat_completions(
          metadata={
              "user_id": "user_123",
              "topic": "education"
          },
          limit=5
      )
      
      print("Education-related completions:")
      for completion in completions.data:
          print(f"- {completion.id}: {completion.model}")
  ```
</CodeGroup>

### Get Specific Completion

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  async function getCompletionDetails(completionId: string) {
    try {
      // Get completion metadata
      const completion = await sudo.router.getChatCompletion(completionId);
      
      // Get completion messages
      const messages = await sudo.router.getChatCompletionMessages(completionId);
      
      return {
        completion,
        messages
      };
    } catch (error) {
      console.error("Get completion details error:", error);
      return null;
    }
  }

  // Usage
  async function completionDetailsExample() {
    const completionId = "chatcmpl-abc123";  // Replace with actual ID
    const details = await getCompletionDetails(completionId);
    
    if (details) {
      console.log(`Completion ID: ${details.completion.id}`);
      console.log(`Model: ${details.completion.model}`);
      console.log(`Created: ${details.completion.created}`);
      console.log("\nMessages:");
      details.messages.data.forEach(message => {
        console.log(`- ${message.role}: ${message.content}`);
      });
    }
  }

  completionDetailsExample();
  ```

  ```python Python theme={null}
  import os
  from sudo import Sudo

  def get_completion_details(completion_id):
      """Get detailed information about a specific completion"""
      
      with Sudo(
          server_url="https://sudoapp.dev/api",
          api_key=os.getenv("SUDO_API_KEY"),
      ) as client:
          
          # Get completion metadata
          completion = client.router.get_chat_completion(completion_id)
          
          # Get completion messages
          messages = client.router.get_chat_completion_messages(completion_id)
          
          return {
              "completion": completion,
              "messages": messages
          }

  # Usage
  completion_id = "chatcmpl-abc123"  # Replace with actual ID
  details = get_completion_details(completion_id)

  print(f"Completion ID: {details['completion'].id}")
  print(f"Model: {details['completion'].model}")
  print(f"Created: {details['completion'].created}")
  print("\nMessages:")
  for message in details['messages'].data:
      print(f"- {message.role}: {message.content}")
  ```
</CodeGroup>

## Updating Completions

### Update Metadata

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  async function updateCompletionMetadata(completionId: string, newMetadata: Record<string, any>) {
    try {
      const updatedCompletion = await sudo.router.updateChatCompletion({
        completionId: completionId,
        metadata: newMetadata
      });
      
      return updatedCompletion;
    } catch (error) {
      console.error("Update completion metadata error:", error);
      return null;
    }
  }

  // Example: Add rating and feedback
  async function updateMetadataExample() {
    const newMetadata = {
      userId: "user_123",
      topic: "education", 
      rating: "5",
      feedback: "very_helpful",
      reviewed: "true"
    };

    const updated = await updateCompletionMetadata("chatcmpl-abc123", newMetadata);
    if (updated) {
      console.log(`Updated completion ${updated.id}`);
      console.log(`New metadata: ${JSON.stringify(updated.metadata)}`);
    }
  }

  updateMetadataExample();
  ```

  ```python Python theme={null}
  import os
  from sudo import Sudo

  def update_completion_metadata(completion_id, new_metadata):
      """Update metadata for a stored completion"""
      
      with Sudo(
          server_url="https://sudoapp.dev/api",
          api_key=os.getenv("SUDO_API_KEY"),
      ) as client:
          
          updated_completion = client.router.update_chat_completion(
              completion_id=completion_id,
              metadata=new_metadata
          )
          
          return updated_completion

  # Example: Add rating and feedback
  new_metadata = {
      "user_id": "user_123",
      "topic": "education", 
      "rating": "5",
      "feedback": "very_helpful",
      "reviewed": "true"
  }

  updated = update_completion_metadata("chatcmpl-abc123", new_metadata)
  print(f"Updated completion {updated.id}")
  print(f"New metadata: {updated.metadata}")
  ```
</CodeGroup>

## Deleting Completions

### Delete Single Completion

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  async function deleteCompletion(completionId: string) {
    try {
      const result = await sudo.router.deleteChatCompletion(completionId);
      return result;
    } catch (error) {
      console.error("Delete completion error:", error);
      return null;
    }
  }

  // Delete a completion
  async function deleteCompletionExample() {
    const result = await deleteCompletion("chatcmpl-abc123");
    if (result) {
      console.log(`Deletion result: ${JSON.stringify(result)}`);
    }
  }

  deleteCompletionExample();
  ```

  ```python Python theme={null}
  import os
  from sudo import Sudo

  def delete_completion(completion_id):
      """Delete a stored completion"""
      
      with Sudo(
          server_url="https://sudoapp.dev/api",
          api_key=os.getenv("SUDO_API_KEY"),
      ) as client:
          
          result = client.router.delete_chat_completion(completion_id)
          return result

  # Delete a completion
  result = delete_completion("chatcmpl-abc123")
  print(f"Deletion result: {result}")
  ```
</CodeGroup>

<Note>
  CRUD operations are only available for completions created with `store=True`. This feature is designed for OpenAI API compatibility and works with both Python and TypeScript SDKs.
</Note>

## Summary

The Sudo SDK provides comprehensive functionality for building AI-powered applications in both Python and TypeScript:

* **System Endpoints**: Monitor API health and discover available models
* **Chat Completion**: Generate responses from various AI models with extensive customization
* **Streaming**: Real-time response generation for interactive applications
* **Tool Calling**: Enable AI models to execute functions and interact with external systems
* **Structured Output**: Generate validated JSON responses for reliable data extraction
* **Image Input**: Process images and multimodal content with vision-capable models
* **Reasoning**: Access advanced reasoning capabilities for complex problem-solving
* **CRUD Operations**: Manage stored completions for analysis and improvement

Both SDKs are designed for production use with comprehensive error handling, async support, and best practices built-in. Start with basic chat completions and gradually add advanced features as needed.

**Resources:**

* **Python**: [GitHub Repository](https://github.com/sudoappai/sudo-python) | [PyPI Package](https://pypi.org/project/sudo-ai/)
* **TypeScript**: [GitHub Repository](https://github.com/sudoappai/sudo-typescript) | [npm Package](https://www.npmjs.com/package/sudo-ai)