Skip to main content

TypeScript SDK

The official TypeScript SDK for Deeployd provides full access to the platform API with type safety and autocompletion.

Installation​

npm install @deeployd/sdk
# or
yarn add @deeployd/sdk
# or
pnpm add @deeployd/sdk

Quick Start​

import { Deeployd } from '@deeployd/sdk';

const client = new Deeployd({
  apiKey: process.env.DEEPLOYD_API_KEY
});

// Create an agent
const agent = await client.agents.create({
  name: 'My Assistant',
  systemPrompt: 'You are a helpful assistant.',
  model: 'claude-sonnet-4-20250514'
});

// Start a conversation
const conversation = await client.conversations.create({
  agentId: agent.id
});

// Send a message
const response = await client.conversations.chat(conversation.id, {
  message: 'Hello!'
});

console.log(response.content);

Configuration​

Basic Configuration​

const client = new Deeployd({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.deeployd.com/v1',  // Optional
  timeout: 30000,                            // Optional, in ms
});

Environment Variables​

# .env
DEEPLOYD_API_KEY=your-api-key
DEEPLOYD_BASE_URL=https://api.deeployd.com/v1
// Auto-reads from environment
const client = new Deeployd();

Custom HTTP Client​

import { Deeployd } from '@deeployd/sdk';

const client = new Deeployd({
  apiKey: 'your-api-key',
  fetch: customFetchFunction,
  headers: {
    'X-Custom-Header': 'value'
  }
});

Agents API​

Create Agent​

const agent = await client.agents.create({
  name: 'Customer Support',
  description: 'Handles customer inquiries',
  systemPrompt: 'You are a friendly customer support agent...',
  model: 'claude-sonnet-4-20250514',
  tools: ['memory', 'http_request', 'calculator'],
  settings: {
    temperature: 0.7,
    maxTokens: 4096
  }
});

Get Agent​

const agent = await client.agents.get('agent-123');

console.log({
  id: agent.id,
  name: agent.name,
  status: agent.status,
  createdAt: agent.createdAt
});

List Agents​

const agents = await client.agents.list({
  limit: 20,
  offset: 0,
  status: 'active'
});

for (const agent of agents.data) {
  console.log(agent.name);
}

Update Agent​

await client.agents.update('agent-123', {
  name: 'Updated Name',
  systemPrompt: 'Updated prompt...'
});

Delete Agent​

await client.agents.delete('agent-123');

Conversations API​

Create Conversation​

const conversation = await client.conversations.create({
  agentId: 'agent-123',
  metadata: {
    userId: 'user-456',
    sessionId: 'abc123'
  }
});

Send Message​

const response = await client.conversations.chat(conversation.id, {
  message: 'What is the weather today?',
  attachments: [
    {
      type: 'file',
      url: 'https://example.com/document.pdf'
    }
  ]
});

console.log(response.content);
console.log(response.toolCalls);

Stream Response​

const stream = await client.conversations.chatStream(conversation.id, {
  message: 'Write a long story about...'
});

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

Get Conversation History​

const messages = await client.conversations.getMessages(conversation.id, {
  limit: 50
});

for (const message of messages.data) {
  console.log(`${message.role}: ${message.content}`);
}

List Conversations​

const conversations = await client.conversations.list({
  agentId: 'agent-123',
  limit: 20
});

Delete Conversation​

await client.conversations.delete(conversation.id);

Tools API​

List Available Tools​

const tools = await client.tools.list();

for (const tool of tools.data) {
  console.log({
    name: tool.name,
    description: tool.description,
    category: tool.category,
    parameters: tool.parameters
  });
}

Create Custom Tool​

const tool = await client.tools.create({
  name: 'get_stock_price',
  description: 'Get the current stock price for a symbol',
  type: 'http',
  config: {
    method: 'GET',
    url: 'https://api.stocks.com/v1/price/${symbol}',
    headers: {
      'Authorization': 'Bearer ${secrets.STOCKS_API_KEY}'
    }
  },
  parameters: {
    type: 'object',
    properties: {
      symbol: {
        type: 'string',
        description: 'Stock symbol (e.g., AAPL)'
      }
    },
    required: ['symbol']
  }
});

Update Tool​

await client.tools.update('tool-123', {
  description: 'Updated description'
});

Delete Tool​

await client.tools.delete('tool-123');

Tasks API​

Create Task​

const task = await client.tasks.create({
  agentId: 'agent-123',
  name: 'Generate Report',
  type: 'manual',
  input: {
    reportType: 'weekly',
    startDate: '2024-01-01'
  },
  priority: 'high'
});

Run Task​

const execution = await client.tasks.run('task-123', {
  input: {
    customParam: 'value'
  }
});

console.log({
  executionId: execution.id,
  status: execution.status,
  output: execution.output
});

Get Task Status​

const task = await client.tasks.get('task-123');

console.log({
  status: task.status,
  lastRunAt: task.lastRunAt,
  nextRunAt: task.nextRunAt
});

List Tasks​

const tasks = await client.tasks.list({
  agentId: 'agent-123',
  status: 'active'
});

Schedules API​

Create Schedule​

const schedule = await client.schedules.create({
  taskId: 'task-123',
  name: 'Daily Report',
  frequency: 'cron',
  cronExpression: '0 9 * * *',  // 9 AM daily
  timezone: 'Europe/Paris',
  enabled: true
});

Update Schedule​

await client.schedules.update('schedule-123', {
  cronExpression: '0 10 * * *',  // Changed to 10 AM
  enabled: true
});

Pause/Resume Schedule​

// Pause
await client.schedules.pause('schedule-123');

// Resume
await client.schedules.resume('schedule-123');

Triggers API​

Create Webhook Trigger​

const trigger = await client.triggers.create({
  taskId: 'task-123',
  name: 'GitHub Push',
  type: 'webhook',
  config: {
    secret: 'webhook-secret',
    inputMapping: {
      branch: '$.ref',
      commit: '$.head_commit.id'
    }
  }
});

console.log(trigger.webhookUrl);
// https://api.deeployd.com/v1/triggers/trigger-123/webhook

List Triggers​

const triggers = await client.triggers.list({
  taskId: 'task-123'
});

Memory API​

Store Memory​

await client.memory.store('agent-123', {
  key: 'user_preference',
  value: {
    theme: 'dark',
    language: 'en'
  },
  ttl: 86400  // Optional: expire after 24 hours
});

Retrieve Memory​

const memory = await client.memory.get('agent-123', 'user_preference');
console.log(memory.value);

Search Memory​

const results = await client.memory.search('agent-123', {
  query: 'user preferences',
  limit: 10
});

Delete Memory​

await client.memory.delete('agent-123', 'user_preference');

Teams API​

Create Team​

const team = await client.teams.create({
  name: 'Engineering',
  description: 'Engineering team'
});

Add Members​

await client.teams.addMember('team-123', {
  userId: 'user-456',
  role: 'member'
});

Remove Members​

await client.teams.removeMember('team-123', 'user-456');

Store API​

Browse Listings​

const listings = await client.store.browse({
  category: 'support',
  pricing: 'free',
  sortBy: 'popular',
  limit: 20
});

Install Listing​

const install = await client.store.install('listing-123');
console.log(install.agentId);  // New agent created

Create Review​

await client.store.createReview('listing-123', {
  rating: 5,
  title: 'Great agent!',
  content: 'This agent saved me hours of work.'
});

Error Handling​

Error Types​

import {
  Deeployd,
  DeeploidError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError
} from '@deeployd/sdk';

try {
  await client.agents.get('nonexistent');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Agent not found');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.log('Validation error:', error.errors);
  } else if (error instanceof DeeploidError) {
    console.log('API error:', error.message);
  }
}

Retry Configuration​

const client = new Deeployd({
  apiKey: 'your-api-key',
  retry: {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 30000,
    retryOn: [429, 500, 502, 503, 504]
  }
});

TypeScript Types​

Import Types​

import type {
  Agent,
  Conversation,
  Message,
  Tool,
  Task,
  Schedule,
  Trigger,
  Team,
  StoreListing
} from '@deeployd/sdk';

const agent: Agent = await client.agents.get('agent-123');

Generic Responses​

import type { PaginatedResponse } from '@deeployd/sdk';

const response: PaginatedResponse<Agent> = await client.agents.list();

console.log({
  data: response.data,
  total: response.total,
  limit: response.limit,
  offset: response.offset
});

Pagination​

Manual Pagination​

let offset = 0;
const limit = 20;
let hasMore = true;

while (hasMore) {
  const response = await client.agents.list({ limit, offset });

  for (const agent of response.data) {
    console.log(agent.name);
  }

  offset += limit;
  hasMore = response.data.length === limit;
}

Auto-Pagination​

for await (const agent of client.agents.listAll()) {
  console.log(agent.name);
}

Webhooks​

Verify Webhook Signature​

import { verifyWebhookSignature } from '@deeployd/sdk';

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-deeployd-signature'];
  const timestamp = req.headers['x-deeployd-timestamp'];

  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    timestamp,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
});

Best Practices​

Use Environment Variables​

// Don't hardcode API keys
const client = new Deeployd({
  apiKey: process.env.DEEPLOYD_API_KEY
});

Handle Errors Gracefully​

async function safeGetAgent(id: string) {
  try {
    return await client.agents.get(id);
  } catch (error) {
    if (error instanceof NotFoundError) {
      return null;
    }
    throw error;
  }
}

Use Streaming for Long Responses​

// Better for long responses
const stream = await client.conversations.chatStream(id, { message });
for await (const chunk of stream) {
  // Process incrementally
}

Reuse Client Instance​

// Create once
const client = new Deeployd({ apiKey });

// Reuse across requests
export { client };

Next: Learn about the Python SDK for Python applications.