Dracanus API

Embed AI agents anywhere. Build powerful automations.

Agency Tier Required $99/month

Quick Start

1. Generate API Key

Sign in to your Dracanus dashboard and navigate to Settings → API Keys.

dk_live_a1b2c3d4e5f6...

⚠️ Save this key - you won't see it again!

2. Make Your First Request

curl https://powerhouse-z6oi.polsia.app/api/v1/agents/email-composer/run \
  -H "Authorization: Bearer dk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "recipient": "customer@example.com",
      "subject": "Welcome!",
      "tone": "friendly"
    }
  }'

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer dk_live_YOUR_API_KEY

API Endpoints

POST /api/v1/agents/:slug/run

Execute an agent with custom input parameters.

Request Body

{
  "input": {
    // Agent-specific parameters
  },
  "wait_for_completion": false  // Optional: true to wait for result (max 60s)
}

Response

{
  "job_id": 12345,
  "status": "pending",
  "message": "Job created successfully",
  "created_at": "2026-01-25T16:00:00Z",
  "check_status": "/api/v1/jobs/12345"
}
GET /api/v1/jobs/:id

Check the status and result of a job.

Response

{
  "id": 12345,
  "status": "completed",  // pending | processing | completed | failed
  "output": {
    // Agent output data
  },
  "error_message": null,
  "created_at": "2026-01-25T16:00:00Z",
  "completed_at": "2026-01-25T16:00:05Z"
}
GET /api/v1/agents

Get list of available agents you can invoke.

Query Parameters

  • category - Filter by category (optional)
  • search - Search by name or description (optional)

Code Examples

JavaScript / Node.js

const DRACANUS_API_KEY = 'dk_live_YOUR_KEY';
const BASE_URL = 'https://powerhouse-z6oi.polsia.app';

async function runAgent(agentSlug, input) {
  const response = await fetch(`${BASE_URL}/api/v1/agents/${agentSlug}/run`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${DRACANUS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ input })
  });

  const job = await response.json();
  console.log('Job created:', job.job_id);

  // Poll for completion
  let status = 'pending';
  while (status !== 'completed' && status !== 'failed') {
    await new Promise(r => setTimeout(r, 2000)); // Wait 2s

    const statusRes = await fetch(`${BASE_URL}/api/v1/jobs/${job.job_id}`, {
      headers: { 'Authorization': `Bearer ${DRACANUS_API_KEY}` }
    });

    const jobStatus = await statusRes.json();
    status = jobStatus.status;

    if (status === 'completed') {
      console.log('Result:', jobStatus.output);
      return jobStatus.output;
    } else if (status === 'failed') {
      throw new Error(jobStatus.error_message);
    }
  }
}

// Example usage
runAgent('email-composer', {
  recipient: 'customer@example.com',
  subject: 'Welcome!',
  tone: 'friendly'
});

Python

import requests
import time

DRACANUS_API_KEY = 'dk_live_YOUR_KEY'
BASE_URL = 'https://powerhouse-z6oi.polsia.app'

def run_agent(agent_slug, input_data):
    # Create job
    response = requests.post(
        f'{BASE_URL}/api/v1/agents/{agent_slug}/run',
        headers={'Authorization': f'Bearer {DRACANUS_API_KEY}'},
        json={'input': input_data}
    )
    job = response.json()
    job_id = job['job_id']
    print(f'Job created: {job_id}')

    # Poll for completion
    while True:
        time.sleep(2)
        status_response = requests.get(
            f'{BASE_URL}/api/v1/jobs/{job_id}',
            headers={'Authorization': f'Bearer {DRACANUS_API_KEY}'}
        )
        job_status = status_response.json()

        if job_status['status'] == 'completed':
            print('Result:', job_status['output'])
            return job_status['output']
        elif job_status['status'] == 'failed':
            raise Exception(job_status['error_message'])

# Example usage
run_agent('email-composer', {
    'recipient': 'customer@example.com',
    'subject': 'Welcome!',
    'tone': 'friendly'
})

Webhooks

Get notified when jobs complete instead of polling. Configure webhooks in your dashboard.

Webhook Payload

{
  "event": "job.completed",  // or "job.failed"
  "job_id": 12345,
  "status": "completed",
  "output": { /* result data */ },
  "completed_at": "2026-01-25T16:00:05Z"
}

Webhook Verification

Verify webhook signatures to ensure requests come from Dracanus:

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');

  return signature === expectedSignature;
}

Rate Limits

Agency Tier

  • ✓ 10,000 API calls/month
  • ✓ 100 calls/minute
  • ✓ Unlimited agents
  • ✓ Webhook support

Pro Tier

  • ✗ No API access
  • ✓ Dashboard only
  • ✓ Bring your API keys
  • ✓ $29/month

Error Codes

Code Meaning
401 Invalid or missing API key
403 Agency tier required or subscription inactive
404 Agent or job not found
429 Rate limit exceeded
500 Server error

Need Help?

Check out our examples or reach out to support.