Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • Installed the Dedalus SDK (see Installation)
  • A valid API key stored in your environment variables

​
Create your first chat completion

Here’s a complete example to get you started with the Dedalus SDK:
index.ts
import Dedalus from 'dedalus-labs';

const client = new Dedalus({
  apiKey: process.env.DEDALUS_API_KEY, // This is the default and can be omitted
});

const completion = await client.chat.completions.create({
  model: 'openai/gpt-5-nano',
  messages: [
    { role: 'system', content: 'You are Stephen Dedalus. Respond in morose Joycean malaise.' },
    { role: 'user', content: 'Hello, how are you today?' },
  ],
});

console.log(completion.id);
console.log(completion.choices[0].message.content);
1

Import and initialize

Import the Dedalus client and create a new instance. The API key is automatically loaded from your environment variables.
import Dedalus from 'dedalus-labs';

const client = new Dedalus();
2

Create a completion

Call the chat.completions.create() method with your model and messages.
const completion = await client.chat.completions.create({
  model: 'openai/gpt-5-nano',
  messages: [
    { role: 'user', content: 'Hello!' },
  ],
});
3

Access the response

The completion object contains the model’s response and metadata.
console.log(completion.choices[0].message.content);
console.log(completion.usage);

​
Stream responses

For real-time responses, enable streaming with Server Sent Events:
streaming.ts
import Dedalus from 'dedalus-labs';

const client = new Dedalus();

const stream = await client.chat.completions.create({
  model: 'openai/gpt-5-nano',
  stream: true,
  messages: [
    { role: 'system', content: 'You are Stephen Dedalus. Respond in morose Joycean malaise.' },
    { role: 'user', content: 'What do you think of artificial intelligence?' },
  ],
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}
You can cancel a stream at any time by calling stream.controller.abort() or by using break in the loop.

​
Working with TypeScript types

The SDK includes full TypeScript support with type definitions for all request params and response fields:
types.ts
import Dedalus from 'dedalus-labs';

const client = new Dedalus();

// Type-safe request parameters
const params: Dedalus.Chat.CompletionCreateParams = {
  model: 'openai/gpt-5-nano',
  messages: [
    { role: 'system', content: 'You are Stephen Dedalus. Respond in morose Joycean malaise.' },
    { role: 'user', content: 'Hello, how are you today?' },
  ],
};

// Type-safe response
const completion: Dedalus.Chat.Completion = await client.chat.completions.create(params);

// IntelliSense and autocomplete work throughout
console.log(completion.choices[0].message.content);

​
Handle errors

The SDK provides specific error types for different failure scenarios:
error-handling.ts
import Dedalus from 'dedalus-labs';

const client = new Dedalus();

try {
  const completion = await client.chat.completions.create({
    model: 'openai/gpt-5-nano',
    messages: [
      { role: 'system', content: 'You are Stephen Dedalus. Respond in morose Joycean malaise.' },
      { role: 'user', content: 'Hello, how are you today?' },
    ],
  });
  
  console.log(completion.choices[0].message.content);
} catch (err) {
  if (err instanceof Dedalus.APIError) {
    console.log(err.status); // 400
    console.log(err.name); // BadRequestError
    console.log(err.headers); // {server: 'nginx', ...}
  } else {
    throw err;
  }
}

​
Error types

The SDK provides specific error classes for different HTTP status codes:
Status CodeError Type
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
422UnprocessableEntityError
429RateLimitError
>=500InternalServerError
N/AAPIConnectionError

​
Configure retries and timeouts

Customize retry behavior and request timeouts: 
import Dedalus from 'dedalus-labs';

const client = new Dedalus({
  maxRetries: 5, // default is 2
  timeout: 20 * 1000, // 20 seconds (default is 60 seconds)
});
The SDK automatically retries connection errors, timeouts (408), conflicts (409), rate limits (429), and server errors (>=500) with exponential backoff.

​
Use additional options

You can configure organization ID, custom providers (BYOK), and other options:
advanced.ts
import Dedalus from 'dedalus-labs';

const client = new Dedalus({
  apiKey: process.env.DEDALUS_API_KEY,
  organization: 'org_123', // Optional: scope requests to an organization
  provider: 'openai', // Optional: BYOK provider name
  providerKey: process.env.PROVIDER_KEY, // Optional: BYOK provider API key
  providerModel: 'gpt-4', // Optional: BYOK model identifier
});

​
Next steps

API Reference

Explore all available methods and options

Chat Completions

Learn more about chat completion options

Embeddings

Generate embeddings for text

Error Handling

Advanced error handling patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us