TypeScript SDK - Send Method - Edgee documentation

The send() method is used to make non-streaming chat completion requests to the Edgee AI Gateway. It returns a Promise<SendResponse> with the model’s response.

Arguments

The send() method accepts a single SendOptions object with the following properties:

Property	Type	Description
`model`	`string`	The model identifier to use (e.g., `"openai/gpt-5.2"`)
`input`	`string \| InputObject`	The input for the completion. Can be a simple string or a structured `InputObject`

Input Types

String Input

When input is a string, it’s automatically converted to a user message:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'What is the capital of France?'
});

// Equivalent to: input: { messages: [{ role: 'user', content: 'What is the capital of France?' }] }
console.log(response.text);
// "The capital of France is Paris."

InputObject

When input is an InputObject, you have full control over the conversation:

Property	Type	Description
`messages`	`Message[]`	Array of conversation messages
`tools`	`Tool[]`	Array of function tools available to the model
`tool_choice`	`ToolChoice`	Controls which tool (if any) the model should call. See Tools documentation for details
`tags`	`string[]`	Optional tags to categorize and label the request for analytics and filtering. Can also be sent via the `x-edgee-tags` header (comma-separated)
`compression_model`	`string`	Compression model for this request: `"claude"`, `"codex"`, `"opencode"`, `"cursor"`. Each model is a bundle of compression strategies. Overrides API key settings when present.

Example with InputObject:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'What is 2+2?' }
    ]
  }
});

console.log(response.text);
// "2+2 equals 4."

Example with Tags:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'Summarize this article' }
    ],
    tags: ['summarization', 'production', 'user-123']
  }
});

Message Object

Each message in the messages array has the following structure:

Property	Type	Description
`role`	`string`	The role of the message sender: `"system"`, `"developer"`, `"user"`, `"assistant"`, or `"tool"`
`content`	`string`	The message content. Required for `system`, `user`, `tool` and `developer` roles. Optional for `assistant` when `tool_calls` is present
`name`	`string`	Optional name for the message sender
`tool_calls`	`ToolCall[]`	Array of tool calls made by the assistant. Only present in `assistant` messages
`tool_call_id`	`string`	ID of the tool call this message is responding to. Required for `tool` role messages

Message Roles

system: System instructions that set the behavior of the assistant
developer: Instructions provided by the application developer, prioritized ahead of user messages.
user: Instructions provided by an end user.
assistant: Assistant responses (can include tool_calls)
tool: Results from tool/function calls (requires tool_call_id)

Example - System and User Messages:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'What is 2+2?' },
      { role: 'assistant', content: '2+2 equals 4.' },
      { role: 'user', content: 'What about 3+3?' }
    ]
  }
});

console.log(response.text);
// "3+3 equals 6."

For complete tool calling examples and best practices, see Tools documentation.

Return Value

The send() method returns a Promise<SendResponse> with the following structure:

SendResponse Object

Property	Type	Description
`choices`	`Choice[]`	Array of completion choices (typically one)
`usage`	`Usage \| undefined`	Token usage information (if provided by the API)
`compression`	`Compression \| undefined`	Token compression metrics (if compression was applied)

Choice Object

Each choice in the choices array contains:

Property	Type	Description
`index`	`number`	The index of this choice in the array
`message`	`Message`	The assistant’s message response
`finish_reason`	`string \| null`	Reason why the generation stopped. Possible values: `"stop"`, `"length"`, `"tool_calls"`, `"content_filter"`, or `null`

Example - Handling Multiple Choices:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Give me a creative idea.'
});

// Process all choices
response.choices.forEach((choice, index) => {
  console.log(`Choice ${index}:`, choice.message.content);
  console.log(`Finish reason: ${choice.finish_reason}`);
});

Message Object (in Response)

The message in each choice has:

Property	Type	Description
`role`	`string`	The role of the message (typically `"assistant"`)
`content`	`string \| null`	The text content of the response. `null` when `tool_calls` is present
`tool_calls`	`ToolCall[] \| undefined`	Array of tool calls requested by the model (if any). See Tools documentation for details

Usage Object

Token usage information (when available):

Property	Type	Description
`prompt_tokens`	`number`	Number of tokens in the prompt (after compression if applied)
`completion_tokens`	`number`	Number of tokens in the completion
`total_tokens`	`number`	Total tokens used (prompt + completion)

Example - Accessing Token Usage:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Explain quantum computing briefly.'
});

if (response.usage) {
  console.log(`Prompt tokens: ${response.usage.prompt_tokens}`);
  console.log(`Completion tokens: ${response.usage.completion_tokens}`);
  console.log(`Total tokens: ${response.usage.total_tokens}`);
}

Compression Object

Token compression metrics (when compression is applied):

Property	Type	Description
`saved_tokens`	`number`	Number of tokens saved by compression
`cost_savings`	`number`	Estimated cost savings in micro-units (e.g. 27000 = $0.027)
`reduction`	`number`	Percentage reduction (e.g. 48 = 48%, may be fractional)
`time_ms`	`number`	Time taken for compression in milliseconds

Example - Accessing Compression Metrics:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: {
    messages: [
      { role: 'user', content: 'Analyze this long document with lots of context...' }
    ],
    compression_model: "claude",
  }
});

if (response.compression) {
  console.log(`Saved tokens: ${response.compression.saved_tokens}`);
  console.log(`Reduction: ${response.compression.reduction}%`);
  console.log(`Cost savings: $${(response.compression.cost_savings / 1_000_000).toFixed(3)}`);
  console.log(`Time: ${response.compression.time_ms} ms`);
}

The compression object is only present when token compression is applied to the request. Simple queries may not trigger compression.

Convenience Properties

The SendResponse class provides convenience getters for easier access:

Property	Type	Description
`text`	`string \| null`	Shortcut to `choices[0].message.content`
`message`	`Message \| null`	Shortcut to `choices[0].message`
`finishReason`	`string \| null`	Shortcut to `choices[0].finish_reason`
`toolCalls`	`ToolCall[] \| null`	Shortcut to `choices[0].message.tool_calls`

Example - Using Convenience Properties:

const response = await edgee.send({
  model: 'gpt-5.2',
  input: 'Hello!'
});

// Instead of: response.choices[0].message.content
console.log(response.text);

// Instead of: response.choices[0].message
console.log(response.message);

// Instead of: response.choices[0].finish_reason
console.log(response.finishReason);

// Instead of: response.choices[0].message.tool_calls
if (response.toolCalls) {
  console.log('Tool calls:', response.toolCalls);
}

Error Handling

The send() method can throw errors in several scenarios:

try {
  const response = await edgee.send({
    model: 'gpt-5.2',
    input: 'Hello!'
  });
} catch (error) {
  if (error instanceof Error) {
    // API errors: "API error {status}: {message}"
    // Network errors: Standard fetch errors
    console.error('Request failed:', error.message);
  }
}

Common Errors

API errors: Error: API error {status}: {message} - The API returned an error status
Network errors: Standard fetch network errors
Invalid input: Errors from invalid request structure

​Arguments

​Input Types

​String Input

​InputObject

​Message Object

​Message Roles

​Return Value

​SendResponse Object

​Choice Object

​Message Object (in Response)

​Usage Object

​Compression Object

​Convenience Properties

​Error Handling

​Common Errors

Arguments

Input Types

String Input

InputObject

Message Object

Message Roles

Return Value

SendResponse Object

Choice Object

Message Object (in Response)

Usage Object

Compression Object

Convenience Properties

Error Handling

Common Errors