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?"
      }
    ],
    "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"
      }
    },
    "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"
      }
    },
    "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?"
      }
    ],
    "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"
      }
    ],
    "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 }],
      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

Getting Started

Core API

Tools

Personalities

Reference

Quick Start

Quick Start

Prerequisites

1. Make Your First Request

2. Try Different Personalities

3. Use Tools

4. Try Streaming (Advanced)

5. Speech-to-Text

Next Steps

Explore API Reference

Learn About Tools

Personalities Guide

​Quick Start

​Prerequisites

​1. Make Your First Request

​2. Try Different Personalities

​3. Use Tools

​4. Try Streaming (Advanced)

​5. Speech-to-Text

​Next Steps

Explore API Reference

Learn About Tools

Personalities Guide

Quick Start

Prerequisites

1. Make Your First Request

2. Try Different Personalities

3. Use Tools

4. Try Streaming (Advanced)

5. Speech-to-Text

Next Steps