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:

usage

object

required

Token usage statistics for the API call

usage.inputTokens

number

required

Number of input tokens processed

usage.outputTokens

number

required

Number of output tokens generated

usage.totalTokens

number

required

Total tokens used (input + output)

usage.reasoningTokens

number

Tokens used for reasoning (if applicable)

usage.cachedInputTokens

number

Cached input tokens (cost savings)

finishReason

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

warnings

Array

Array of warning messages (usually empty)

providerMetadata

object

Provider-specific metadata (OpenAI, etc.)

traceId

string

required

Unique request trace identifier for debugging

Generate Endpoint Response

Complete Response Structure

{
  "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

steps[].stepType

string

Type of processing step ("initial", "tool_execution", etc.)

steps[].toolCalls

Array

Tool calls made during this step

steps[].toolResults

Array

Results from tool executions

steps[].content

Array

Content generated during this step

steps[].text

string

Text content for this step

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

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

Tool Result Event Format

{
  "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

{
  "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

{
  "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

{
  "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

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

Tool Call Format

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

Tool Result Format

type ToolResult = {
  toolCallId: string;
  toolName: string;
  result: any;
};

Response Size Considerations

Response Size Limits: Large responses may be truncated. Use streaming for long conversations.

Tool Results: Complex tool results are included in full, monitor response sizes.

Token Usage: Track usage statistics to manage costs and rate limits.

Documentation Index

​Response Formats

​Common Response Fields

​Generate Endpoint Response

​Complete Response Structure

​Step Object Structure

​Streaming Response Events

​Event Types

​Tool Call Event Format

​Tool Result Event Format

​Speech-to-Text Response

​Memory Management Response

​Thread Creation Response

​Error Response Format

​Common Error Codes

​Data Types Reference

​Message Format

​Tool Call Format

​Tool Result Format

​Response Size Considerations

Response Formats

Common Response Fields

Generate Endpoint Response

Complete Response Structure

Step Object Structure

Streaming Response Events

Event Types

Tool Call Event Format

Tool Result Event Format

Speech-to-Text Response

Memory Management Response

Thread Creation Response

Error Response Format

Common Error Codes

Data Types Reference

Message Format

Tool Call Format

Tool Result Format

Response Size Considerations