Skip to main content

Build on Siya's Foundation

Comprehensive API documentation for integrating Siya into your applications, workflows, and tools. Whether you’re building extensions, automating tasks, or creating custom integrations, this reference provides everything you need.
The Siya API is currently in development. CLI and REST API access coming soon!

​
API Overview

Siya's API architecture enables powerful integrations

​
Desktop Integration APIs

Available Now: Desktop Automation

Integrate with Siya Desktop using native macOS technologies
  • URL Schemes
  • AppleScript
  • Shortcuts Integration

Deep Linking Protocol

Control Siya through URL schemes from any application

URL Scheme Reference

// Open Siya with a prompt
let url = URL(string: "siya://chat?prompt=Help%20me%20debug%20this%20Swift%20code")!
NSWorkspace.shared.open(url)

​
Coming Soon: REST API

RESTful API Interface

Full-featured REST API for programmatic access (Coming Soon)
The REST API is currently in development. Expected release: Q1 2025
  • API Design Preview
  • Authentication
  • SDKs

Planned REST API architecture

Planned Endpoints

POST   /auth/login
POST   /auth/refresh
POST   /auth/logout
GET    /auth/status

{
  "model": "claude-opus-4",
  "messages": [
    {
      "role": "user",
      "content": "Help me optimize this function"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 4000,
  "tools": ["code_analysis", "testing"],
  "stream": false
}

​
Coming Soon: CLI

Command Line Interface

Powerful CLI for terminal workflows (Coming Soon)
The CLI is currently in development. Expected release: Q1 2025
  • CLI Preview
  • Planned Commands
  • CLI Configuration
# Install via Homebrew (macOS)
brew install siya-cli

# Install via npm
npm install -g @siya/cli

# Install via curl
curl -fsSL https://siya.com/install.sh | sh

​
Integration Examples

Real-World Integration Patterns

Examples of how to integrate Siya into your workflow
  • IDE Integration
  • CI/CD Integration
  • Automation Scripts

VS Code Extension

// VS Code extension example
const vscode = require('vscode');

function activate(context) {
    // Register command
    let disposable = vscode.commands.registerCommand(
        'siya.askQuestion',
        async () => {
            // Get selected text
            const editor = vscode.window.activeTextEditor;
            const selection = editor.selection;
            const text = editor.document.getText(selection);
            
            // Open Siya with context
            const prompt = encodeURIComponent(
                `Explain this code:\n${text}`
            );
            vscode.env.openExternal(
                vscode.Uri.parse(`siya://chat?prompt=${prompt}`)
            );
        }
    );
    
    context.subscriptions.push(disposable);
}

// IntelliJ IDEA plugin example
class SiyaAction : AnAction() {
    override fun actionPerformed(e: AnActionEvent) {
        val editor = e.getData(CommonDataKeys.EDITOR)
        val selectedText = editor?.selectionModel?.selectedText
        
        if (selectedText != null) {
            val prompt = URLEncoder.encode(
                "Review this code: $selectedText",
                "UTF-8"
            )
            Desktop.getDesktop().browse(
                URI("siya://chat?prompt=$prompt")
            )
        }
    }
}

​
Webhooks & Events

Event-Driven Integration

Subscribe to Siya events for real-time integration (Coming Soon)
  • Webhook Configuration
  • Event Types
{
  "webhooks": {
    "endpoints": [
      {
        "url": "https://api.company.com/siya-webhook",
        "events": ["task.completed", "error.occurred"],
        "secret": "webhook_secret_key"
      }
    ],
    "retry": {
      "attempts": 3,
      "backoff": "exponential"
    }
  }
}

​
Rate Limits & Quotas

API Usage Limits

Understand rate limits and quotas for API usage

​
Error Handling

Robust Error Handling

Handle API errors gracefully
try {
    const response = await siya.chat.create({
        model: 'claude-opus-4',
        messages: messages
    });
} catch (error) {
    if (error.status === 429) {
        // Rate limit exceeded
        const retryAfter = error.headers['retry-after'];
        await sleep(retryAfter * 1000);
        // Retry request
    } else if (error.status === 401) {
        // Authentication failed
        await refreshToken();
    } else if (error.status >= 500) {
        // Server error - implement exponential backoff
        await retryWithBackoff(request);
    }
}

​
Best Practices

API Integration Best Practices

Follow these guidelines for robust integrations

Security

Do's

  • Store API keys securely
  • Use environment variables
  • Implement request signing
  • Validate webhooks
  • Use HTTPS always
  • Rotate keys regularly

Don'ts

  • Hardcode credentials
  • Log sensitive data
  • Share API keys
  • Ignore SSL errors
  • Skip authentication
  • Trust user input
1

Implement Caching

Cache responses when appropriate
2

Use Batch Operations

Group related requests together
3

Handle Rate Limits

Implement proper backoff strategies
4

Optimize Payloads

Send only necessary data
  • Implement retry logic with exponential backoff
  • Handle timeouts gracefully
  • Log all API interactions
  • Monitor API health
  • Have fallback strategies

​
Summary

Build Amazing Integrations

Siya’s API ecosystem provides powerful integration capabilities, from simple URL schemes available today to the comprehensive REST API and CLI coming soon. Whether you’re automating workflows, building extensions, or creating custom integrations, Siya’s APIs give you the flexibility and power you need.

Get Started Today

Start with Desktop integration

Stay Updated

Join the developer newsletter
Build on Siya. Extend your capabilities. Create the future.