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

# Quick Start

> Get started with the Blue Oyster API in minutes

# 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:

```bash theme={null}
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"
  }'
```

<ResponseExample>
  ```json theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## 2. Try Different Personalities

Experience the different personality modes:

```bash theme={null}
# 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:

```bash theme={null}
# 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 theme={null}
// 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:

```bash theme={null}
# Upload an audio file for transcription
curl -X POST https://oyester.metaphy.live/stt \
  -F "audio=@/path/to/your/audio.mp3"
```

## Next Steps

<CardGroup cols={3}>
  <Card title="Explore API Reference" icon="code" href="/api/generate">
    Detailed endpoint documentation
  </Card>

  <Card title="Learn About Tools" icon="wrench" href="/tools/weather">
    Discover available tools
  </Card>

  <Card title="Personalities Guide" icon="user" href="/personalities/overview">
    Choose the right personality
  </Card>
</CardGroup>