Developer Resources

API Documentation

Build custom skills and integrate with external services using Clawdbot's powerful API. Complete reference for REST endpoints, webhooks, and skill development.

Quick Start: Build Your First Skill

Get started with Clawdbot SDK in just 4 steps

Install SDK

Terminal

bash

npm install @clawdbot/sdk

Initialize Skill Project

Terminal

bash

npx clawdbot-skill init my-skill

Implement Skill Logic

Terminal

bash

// Edit skills/my-skill/index.ts
import { Skill } from '@clawdbot/sdk'

export default class MySkill extends Skill {
  async execute(params: any) {
    // Your skill logic here
    return { success: true }
  }
}

Test and Install

Terminal

bash

# Test locally
clawdbot skills test ./my-skill

# Install to Clawdbot
clawdbot skills install ./my-skill

Authentication

API Key Authentication

Include your API key in the request header

Terminal

bash

curl -X GET https://your-clawdbot.local:3000/api/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

OAuth 2.0

Use OAuth for third-party integrations

Terminal

bash

# Generate OAuth token
clawdbot auth create --client-id YOUR_CLIENT_ID

# Use token in requests
curl -X POST https://your-clawdbot.local:3000/api/v1/assistant/chat \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
  -d '{"message": "Hello, Clawdbot!"}'

REST API

Interact with Clawdbot via RESTful endpoints

GET

/api/v1/status

Get Clawdbot service status and health information

Response

json

{
  "status": "running",
  "version": "1.0.0",
  "uptime": 86400,
  "health": "healthy",
  "skills": {
    "installed": 12,
    "active": 8
  }
}

POST

/api/v1/skills/{skill}/execute

Execute a specific skill with parameters

Response

json

{
  "success": true,
  "result": {
    "action": "voice_command",
    "response": "Lights turned off",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

GET

/api/v1/skills

List all installed skills

Response

json

{
  "skills": [
    {
      "name": "voice-assistant",
      "version": "2.1.0",
      "status": "active",
      "enabled": true
    }
  ]
}

POST

/api/v1/assistant/chat

Send a message to the AI assistant

Response

json

{
  "response": "I can help you with that...",
  "model": "claude-3.5-sonnet",
  "tokens_used": 150,
  "timestamp": "2025-01-15T10:30:00Z"
}

Webhooks

Receive real-time notifications from Clawdbot

skill.activated

Fired when a skill is activated

Payload

json

{
  "event": "skill.activated",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "skill": "voice-assistant",
    "trigger": "wake_word",
    "confidence": 0.95
  }
}

automation.completed

Fired when an automation rule completes

Payload

json

{
  "event": "automation.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "automation": "morning-routine",
    "status": "success",
    "duration_ms": 1250
  }
}

system.alert

Fired for system alerts and warnings

Payload

json

{
  "event": "system.alert",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "severity": "warning",
    "message": "High memory usage detected",
    "memory_percent": 85
  }
}

Skill Development

Build custom skills for Clawdbot

Basic Skill Structure

TypeScript

typescript

// skills/custom-timer/index.ts
import { Skill } from '@clawdbot/sdk'

export default class TimerSkill extends Skill {
  constructor() {
    super({
      name: 'custom-timer',
      version: '1.0.0',
      description: 'Create custom timers',
    })
  }

  async execute(params: { duration: number }) {
    const { duration } = params

    // Create timer
    await this.timers.create(duration, async () => {
      await this.notify('Timer complete!')
    })

    return {
      success: true,
      message: `Timer set for ${duration} seconds`,
    }
  }
}

Skill with Configuration

TypeScript

typescript

// skills/weather-alert/index.ts
import { Skill, SkillConfig } from '@clawdbot/sdk'

const config: SkillConfig = {
  name: 'weather-alert',
  version: '1.0.0',
  description: 'Weather monitoring and alerts',
  dependencies: ['weather-api'],
  permissions: ['location', 'notifications'],
}

export default class WeatherAlertSkill extends Skill {
  constructor() {
    super(config)
  }

  async onEnable() {
    // Set up weather monitoring
    this.schedule.every('1h', () => this.checkWeather())
  }

  async checkWeather() {
    const weather = await this.api.weather.getCurrent()
    if (weather.severity === 'severe') {
      await this.notifications.send({
        title: 'Severe Weather Alert',
        body: weather.description,
        urgency: 'high',
      })
    }
  }
}

Registering Skill Commands

TypeScript

typescript

// skills/home-automation/index.ts
import { Skill, Command } from '@clawdbot/sdk'

export default class HomeAutomationSkill extends Skill {
  constructor() {
    super({
      name: 'home-automation',
      version: '1.0.0',
      description: 'Smart home controls',
    })
  }

  registerCommands(): Command[] {
    return [
      {
        name: 'lights.on',
        handler: async (args) => {
          await this.api.hue.turnOn(args.room)
          return `Lights on in ${args.room}`
        },
      },
      {
        name: 'thermostat.set',
        handler: async (args) => {
          await this.api.thermostat.setTemperature(args.temp)
          return `Temperature set to ${args.temp}°F`
        },
      },
    ]
  }
}

SDK Reference

Core SDK Methods

Essential methods available in the Clawdbot SDK

Skill Base Class

Extend the Skill base class to create custom skills. Override methods like execute(), onEnable(), and onDisable() to implement behavior.

API Access

Access external APIs through this.api. Built-in clients for weather, calendar, home automation, and more. Add custom API clients easily.

Notifications

Send notifications using this.notify() or this.notifications.send(). Support for different urgency levels and custom payloads.

Scheduling

Schedule tasks with this.schedule.every(), this.schedule.cron(), or this.schedule.once(). Perfect for recurring jobs.

Development Best Practices

• Always handle errors gracefully and return meaningful error messages
• Use TypeScript for type safety and better IDE support
• Write unit tests for your skills using the SDK testing utilities
• Document your skill's configuration options and required permissions
• Use logging for debugging: this.logger.info()

Ready to Build!

You have everything you need to start building Clawdbot skills. Check out the Skills Library for examples, or visit GitHub Examples for complete skill projects.

Continue Exploring

Deepen your understanding of Clawdbot development and deployment.

View CLI Reference Browse Skills Library SDK on GitHub Get Help