API Reference

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

Examples

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

URL Parameters

AppleScript Automation

Full automation support through AppleScript

Basic Commands

-- Activate Siya
tell application "Siya"
    activate
end tell

-- Bring to front
tell application "Siya"
    activate
    set frontmost to true
end tell

Advanced Automation

-- Complete automation example
tell application "Siya"
    activate
    
    -- Start new chat
    new chat
    
    -- Send complex prompt
    set myPrompt to "Analyze this code and suggest improvements"
    send prompt myPrompt
    
    -- Wait for completion
    repeat while is processing
        delay 0.5
    end repeat
    
    -- Get and process response
    set aiResponse to last response
    
    -- Save to file
    save conversation to file "~/Desktop/analysis.md"
    
    -- Clear for next task
    clear memory
end tell

AppleScript Dictionary

Apple Shortcuts

Create powerful automations with Shortcuts app

Create Shortcut

Open Shortcuts app and create new shortcut

Add Siya Action

Search for “Siya” in actions or use URL scheme

Configure Action

Set prompt, model, or other parameters

Test & Save

Run shortcut and save for reuse

Example Shortcuts

Code Review

Get clipboard
Open URL: siya://chat?prompt=Review%20this%20code%3A%20{clipboard}
Wait 2 seconds
Copy Siya response

Daily Standup

Get current date
Open URL: siya://chat?prompt=Generate%20standup%20for%20{date}
Save response to Notes

Shortcut Actions

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

Request/Response Format

{
  "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
}

Secure API Access

Multiple authentication methods for different use cases

API Key Authentication

# Header authentication
curl -X POST https://api.siya.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello Siya"}'

Generate API Key

Create keys in Siya Dashboard

Set Permissions

Configure scope and rate limits

Use in Requests

Include in Authorization header

OAuth 2.0

// OAuth flow example
const auth = new SiyaAuth({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'https://yourapp.com/callback'
});

// Get authorization URL
const authUrl = auth.getAuthorizationUrl({
  scope: ['chat', 'projects', 'models'],
  state: 'random_state'
});

// Exchange code for token
const token = await auth.exchangeCode(code);

Official SDKs

Native SDKs for popular languages (Coming Soon)

JavaScript/TypeScript

npm install @siya/sdk

import { Siya } from '@siya/sdk';

const siya = new Siya({
  apiKey: process.env.SIYA_API_KEY
});

const response = await siya.chat.create({
  model: 'claude-opus-4',
  messages: [...]
});

Python

pip install siya-sdk

from siya import Siya

client = Siya(
    api_key=os.environ["SIYA_API_KEY"]
)

response = client.chat.create(
    model="claude-opus-4",
    messages=[...]
)

Go

go get github.com/siya/siya-go

import "github.com/siya/siya-go"

client := siya.NewClient(
    siya.WithAPIKey(apiKey),
)

resp, err := client.Chat.Create(ctx, &siya.ChatRequest{
    Model: "claude-opus-4",
    Messages: messages,
})

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

# Default configuration
defaults:
  model: claude-sonnet-4
  temperature: 0.7
  max_tokens: 4000

# Project overrides
projects:
  - path: ~/work/frontend
    model: claude-opus-4
    context: 
      - src/
      - package.json
  
  - path: ~/work/backend
    model: deepseek-coder
    context:
      - api/
      - requirements.txt

# Aliases
aliases:
  review: "analyze --detailed --suggest-improvements"
  quick: "ask --model gemini-flash"

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);
}

JetBrains Plugin

// 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")
            )
        }
    }
}

name: Code Review with Siya

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Siya Code Review
        uses: siya/code-review-action@v1
        with:
          api-key: ${{ secrets.SIYA_API_KEY }}
          model: claude-opus-4
          focus-areas:
            - security
            - performance
            - best-practices
      
      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: process.env.SIYA_REVIEW
            })

import subprocess
import urllib.parse

class SiyaAutomation:
    def __init__(self):
        self.base_url = "siya://"
    
    def ask_siya(self, prompt):
        """Send prompt to Siya and get response"""
        encoded = urllib.parse.quote(prompt)
        url = f"{self.base_url}chat?prompt={encoded}"
        
        # Open Siya with prompt
        subprocess.run(["open", url])
    
    def analyze_project(self, path):
        """Open project in Siya"""
        url = f"{self.base_url}project?path={path}"
        subprocess.run(["open", url])
    
    def batch_review(self, files):
        """Review multiple files"""
        for file in files:
            with open(file, 'r') as f:
                content = f.read()
            
            prompt = f"Review this {file}: {content[:1000]}"
            self.ask_siya(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

Performance

Implement Caching

Cache responses when appropriate

Use Batch Operations

Group related requests together

Handle Rate Limits

Implement proper backoff strategies

Optimize Payloads

Send only necessary data

Reliability

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.

Getting Started

Core Concepts

Configuration & Integration

Advanced

API Reference

Build on Siya's Foundation

API Overview

Desktop Integration APIs

Available Now: Desktop Automation

Deep Linking Protocol

AppleScript Automation

Apple Shortcuts

Code Review

Daily Standup

Coming Soon: REST API

RESTful API Interface

Secure API Access

Official SDKs

JavaScript/TypeScript

Python

Go

Coming Soon: CLI

Command Line Interface

Integration Examples

Real-World Integration Patterns

Webhooks & Events

Event-Driven Integration

Rate Limits & Quotas

API Usage Limits

Error Handling

Robust Error Handling

Best Practices

API Integration Best Practices

Do's

Don'ts

Summary

Build Amazing Integrations

Get Started Today

Stay Updated

Getting Started

Core Concepts

Configuration & Integration

Advanced

Build on Siya's Foundation

​API Overview

​Desktop Integration APIs

Available Now: Desktop Automation

Deep Linking Protocol

AppleScript Automation

Apple Shortcuts

Code Review

Daily Standup

​Coming Soon: REST API

RESTful API Interface

Secure API Access

Official SDKs

JavaScript/TypeScript

Python

Go

​Coming Soon: CLI

Command Line Interface

​Integration Examples

Real-World Integration Patterns

​Webhooks & Events

Event-Driven Integration

​Rate Limits & Quotas

API Usage Limits

​Error Handling

Robust Error Handling

​Best Practices

API Integration Best Practices

Do's

Don'ts

​Summary

Build Amazing Integrations

Get Started Today

Stay Updated

API Overview

Desktop Integration APIs

Coming Soon: REST API

Coming Soon: CLI

Integration Examples

Webhooks & Events

Rate Limits & Quotas

Error Handling

Best Practices

Summary