Skip to main content

​
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 TypeDescriptionData Structure
startRun initialization{"type":"start","runId":"uuid"}
step-startStep beginning{"type":"step-start","payload":{"stepType":"initial"},"runId":"uuid"}
textText content chunk{"type":"text","text":"Hello, ","runId":"uuid"}
tool-callTool call initiationTool call object
tool-resultTool execution resultTool result object
step-finishStep completion{"type":"step-finish","payload":{"finishReason":"stop"},"runId":"uuid"}
run-finishRun completion{"type":"run-finish","payload":{"finishReason":"stop"},"runId":"uuid"}
errorError occurredError 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

CodeDescription
TOOL_EXECUTION_FAILEDTool execution error
MEMORY_NOT_INITIALIZEDMongoDB not configured
INVALID_REQUESTMalformed request
RATE_LIMITEDToo many requests
MODEL_ERRORAI model processing error
AUDIO_PROCESSING_ERRORSpeech-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.