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

# Response Formats

> Detailed breakdown of API response structures and data formats

# Response Formats

This reference provides detailed information about the structure and content of API responses across all endpoints.

## Common Response Fields

All successful responses include these standard fields:

<ResponseField name="usage" type="object" required>
  Token usage statistics for the API call
</ResponseField>

<ResponseField name="usage.inputTokens" type="number" required>
  Number of input tokens processed
</ResponseField>

<ResponseField name="usage.outputTokens" type="number" required>
  Number of output tokens generated
</ResponseField>

<ResponseField name="usage.totalTokens" type="number" required>
  Total tokens used (input + output)
</ResponseField>

<ResponseField name="usage.reasoningTokens" type="number">
  Tokens used for reasoning (if applicable)
</ResponseField>

<ResponseField name="usage.cachedInputTokens" type="number">
  Cached input tokens (cost savings)
</ResponseField>

<ResponseField name="finishReason" type="string" required>
  Reason for response completion. Possible values:

  * `"stop"`: Normal completion
  * `"length"`: Response truncated due to length limits
  * `"tool_calls"`: Response ended due to tool usage
</ResponseField>

<ResponseField name="warnings" type="Array">
  Array of warning messages (usually empty)
</ResponseField>

<ResponseField name="providerMetadata" type="object">
  Provider-specific metadata (OpenAI, etc.)
</ResponseField>

<ResponseField name="traceId" type="string" required>
  Unique request trace identifier for debugging
</ResponseField>

## Generate Endpoint Response

### Complete Response Structure

```json theme={null}
{
  "text": "The complete response text from the companion agent.",
  "usage": {
    "inputTokens": 15,
    "outputTokens": 45,
    "totalTokens": 60,
    "reasoningTokens": 0,
    "cachedInputTokens": 0
  },
  "steps": [
    {
      "stepType": "initial",
      "sources": [],
      "files": [],
      "toolCalls": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "args": {
            "location": "Tokyo"
          }
        }
      ],
      "toolResults": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "result": {
            "temperature": 22,
            "feelsLike": 25,
            "humidity": 65,
            "windSpeed": 5,
            "windGust": 8,
            "conditions": "Partly cloudy",
            "location": "Tokyo"
          }
        }
      ],
      "content": [
        {
          "type": "text",
          "text": "The weather in Tokyo is currently 22°C with partly cloudy conditions..."
        }
      ],
      "text": "The weather in Tokyo is currently 22°C with partly cloudy conditions...",
      "reasoningText": "",
      "reasoning": [],
      "staticToolCalls": [],
      "dynamicToolCalls": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "args": {
            "location": "Tokyo"
          },
          "providerMetadata": {}
        }
      ],
      "staticToolResults": [],
      "dynamicToolResults": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "result": {
            "temperature": 22,
            "feelsLike": 25,
            "humidity": 65,
            "windSpeed": 5,
            "windGust": 8,
            "conditions": "Partly cloudy",
            "location": "Tokyo"
          }
        }
      ],
      "finishReason": "stop",
      "usage": {
        "inputTokens": 15,
        "outputTokens": 45,
        "totalTokens": 60,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      },
      "warnings": [],
      "request": {
        "body": {}
      },
      "response": {
        "id": "resp_123",
        "timestamp": "2025-11-21T10:30:00.000Z",
        "modelId": "gpt-5",
        "headers": {},
        "modelMetadata": {},
        "messages": [],
        "uiMessages": [
          {
            "id": "msg_123",
            "role": "assistant",
            "metadata": {
              "createdAt": "2025-11-21T10:30:00.000Z",
              "threadId": "thread-abc123",
              "resourceId": "user-123"
            },
            "parts": [
              {
                "type": "text",
                "text": "The weather in Tokyo is currently 22°C with partly cloudy conditions..."
              }
            ]
          }
        ]
      },
      "providerMetadata": {},
      "totalUsage": {
        "inputTokens": 15,
        "outputTokens": 45,
        "totalTokens": 60,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      },
      "tripwire": false,
      "tripwireReason": "",
      "traceId": "trace-abc123"
    }
  ],
  "finishReason": "stop",
  "warnings": [],
  "providerMetadata": {},
  "request": {
    "body": {}
  },
  "reasoning": [],
  "toolCalls": [
    {
      "toolCallId": "call_weather_123",
      "toolName": "weatherTool",
      "args": {
        "location": "Tokyo"
      },
      "providerMetadata": {}
    }
  ],
  "toolResults": [
    {
      "toolCallId": "call_weather_123",
      "toolName": "weatherTool",
      "result": {
        "temperature": 22,
        "feelsLike": 25,
        "humidity": 65,
        "windSpeed": 5,
        "windGust": 8,
        "conditions": "Partly cloudy",
        "location": "Tokyo"
      }
    }
  ],
  "sources": [],
  "files": [],
  "response": {},
  "totalUsage": {
    "inputTokens": 15,
    "outputTokens": 45,
    "totalTokens": 60,
    "reasoningTokens": 0,
    "cachedInputTokens": 0
  },
  "tripwire": false,
  "tripwireReason": "",
  "traceId": "trace-abc123"
}
```

### Step Object Structure

<ResponseField name="steps[].stepType" type="string">
  Type of processing step (`"initial"`, `"tool_execution"`, etc.)
</ResponseField>

<ResponseField name="steps[].toolCalls" type="Array">
  Tool calls made during this step
</ResponseField>

<ResponseField name="steps[].toolResults" type="Array">
  Results from tool executions
</ResponseField>

<ResponseField name="steps[].content" type="Array">
  Content generated during this step
</ResponseField>

<ResponseField name="steps[].text" type="string">
  Text content for this step
</ResponseField>

## Streaming Response Events

### Event Types

| Event Type    | Description           | Data Structure                                                            |
| ------------- | --------------------- | ------------------------------------------------------------------------- |
| `start`       | Run initialization    | `{"type":"start","runId":"uuid"}`                                         |
| `step-start`  | Step beginning        | `{"type":"step-start","payload":{"stepType":"initial"},"runId":"uuid"}`   |
| `text`        | Text content chunk    | `{"type":"text","text":"Hello, ","runId":"uuid"}`                         |
| `tool-call`   | Tool call initiation  | Tool call object                                                          |
| `tool-result` | Tool execution result | Tool result object                                                        |
| `step-finish` | Step completion       | `{"type":"step-finish","payload":{"finishReason":"stop"},"runId":"uuid"}` |
| `run-finish`  | Run completion        | `{"type":"run-finish","payload":{"finishReason":"stop"},"runId":"uuid"}`  |
| `error`       | Error occurred        | Error object                                                              |

### Tool Call Event Format

```json theme={null}
{
  "type": "tool-call",
  "payload": {
    "toolCallId": "call_123",
    "toolName": "weatherTool",
    "args": {
      "location": "Tokyo"
    },
    "providerMetadata": {}
  },
  "runId": "run_abc123"
}
```

### Tool Result Event Format

```json theme={null}
{
  "type": "tool-result",
  "payload": {
    "toolCallId": "call_123",
    "toolName": "weatherTool",
    "result": {
      "temperature": 22,
      "feelsLike": 25,
      "humidity": 65,
      "windSpeed": 5,
      "windGust": 8,
      "conditions": "Partly cloudy",
      "location": "Tokyo"
    }
  },
  "runId": "run_abc123"
}
```

## Speech-to-Text Response

```json theme={null}
{
  "transcript": "The transcribed text from the audio file.",
  "success": true,
  "timestamp": "2025-11-21T10:30:00.000Z",
  "processingTime": 2450
}
```

## Memory Management Response

### Thread Creation Response

```json theme={null}
{
  "id": "thread-abc123-def456",
  "title": "Morning Meditation Journey",
  "resourceId": "user-123",
  "agentId": "companionAgent",
  "createdAt": "2025-11-21T08:00:00.000Z",
  "updatedAt": "2025-11-21T08:00:00.000Z",
  "metadata": {
    "personality": "friend",
    "createdAt": "2025-11-21T08:00:00.000Z",
    "tags": ["meditation", "mindfulness"]
  }
}
```

## Error Response Format

```json theme={null}
{
  "error": "Error message describing what went wrong",
  "stack": "Stack trace (development only)",
  "code": "ERROR_CODE",
  "details": {
    "additional": "error context"
  }
}
```

### Common Error Codes

| Code                     | Description                      |
| ------------------------ | -------------------------------- |
| `TOOL_EXECUTION_FAILED`  | Tool execution error             |
| `MEMORY_NOT_INITIALIZED` | MongoDB not configured           |
| `INVALID_REQUEST`        | Malformed request                |
| `RATE_LIMITED`           | Too many requests                |
| `MODEL_ERROR`            | AI model processing error        |
| `AUDIO_PROCESSING_ERROR` | Speech-to-text processing failed |

## Data Types Reference

### Message Format

```typescript theme={null}
type Message = {
  role: "user" | "assistant" | "system";
  content: string | Array<{
    type: "input_text" | "output_text";
    text: string;
  }>;
};
```

### Tool Call Format

```typescript theme={null}
type ToolCall = {
  toolCallId: string;
  toolName: string;
  args: Record<string, any>;
  providerMetadata?: any;
};
```

### Tool Result Format

```typescript theme={null}
type ToolResult = {
  toolCallId: string;
  toolName: string;
  result: any;
};
```

## Response Size Considerations

<Note>
  **Response Size Limits**: Large responses may be truncated. Use streaming for long conversations.
</Note>

<Note>
  **Tool Results**: Complex tool results are included in full, monitor response sizes.
</Note>

<Note>
  **Token Usage**: Track usage statistics to manage costs and rate limits.
</Note>