Skip to main content

​
Quick Start

Get up and running with the Blue Oyster Personal Companion API in just a few steps.

​
Prerequisites

  • Basic knowledge of HTTP requests
  • A tool for making API calls (curl, Postman, or your preferred HTTP client)

​
1. Make Your First Request

Send a simple message to the companion agent: 
curl -X POST https://oyester.metaphy.live/api/agents/companionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Hello! Can you help me find inner peace?"
      }
    ],
    "threadId": "demo-thread-001",
    "resourceId": "demo-user"
  }'

{
  "text": "Hello! I'm delighted to help you on your journey toward inner peace. Finding tranquility is a beautiful pursuit that many seek. Would you like me to suggest some meditation practices, recommend peaceful destinations, or share some philosophical insights about finding peace within?",
  "usage": {
    "inputTokens": 15,
    "outputTokens": 67,
    "totalTokens": 82,
    "reasoningTokens": 0,
    "cachedInputTokens": 0
  },
  "finishReason": "stop",
  "warnings": [],
  "traceId": "trace-abc123"
}

​
2. Try Different Personalities

Experience the different personality modes: 
# Guru personality for wisdom
curl -X POST https://oyester.metaphy.live/api/agents/companionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the nature of reality?"
      }
    ],
    "runtimeContext": {
      "metadata": {
        "personality": "guru"
      }
    },
    "threadId": "guru-discussion-001",
    "resourceId": "demo-user"
  }'

# Wanderer personality for exploration
curl -X POST https://oyester.metaphy.live/api/agents/companionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Tell me about spiritual journeys"
      }
    ],
    "runtimeContext": {
      "metadata": {
        "personality": "wanderer"
      }
    },
    "threadId": "wanderer-discussion-001",
    "resourceId": "demo-user"
  }'

​
3. Use Tools

Try the integrated tools for enhanced functionality: 
# Weather information
curl -X POST https://oyester.metaphy.live/api/agents/companionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in Kyoto for meditation?"
      }
    ],
    "threadId": "weather-query-001",
    "resourceId": "demo-user"
  }'

# Find spiritual destinations
curl -X POST https://oyester.metaphy.live/api/agents/companionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Find me peaceful Buddhist temples in Japan"
      }
    ],
    "threadId": "destinations-query-001",
    "resourceId": "demo-user"
  }'

​
4. Try Streaming (Advanced)

For real-time responses, use the streaming endpoint: 
// JavaScript example with streaming
async function streamMessage(message) {
  const response = await fetch('https://oyester.metaphy.live/api/agents/companionAgent/stream', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messages: [{ role: 'user', content: message }],
      threadId: 'stream-demo-001',
      resourceId: 'demo-user'
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        if (data.type === 'text') {
          console.log('Received:', data.text);
        }
      }
    }
  }
}

// Usage
streamMessage("Hello, how can you help me today?");

​
5. Speech-to-Text

Convert audio to text: 
# Upload an audio file for transcription
curl -X POST https://oyester.metaphy.live/stt \
  -F "audio=@/path/to/your/audio.mp3"

​
Next Steps

Explore API Reference

Detailed endpoint documentation

Learn About Tools

Discover available tools

Personalities Guide

Choose the right personality