Embed AI agents anywhere. Build powerful automations.
Sign in to your Dracanus dashboard and navigate to Settings → API Keys.
dk_live_a1b2c3d4e5f6...
⚠️ Save this key - you won't see it again!
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"
}
}'
All API requests must include your API key in the Authorization header:
Authorization: Bearer dk_live_YOUR_API_KEY
/api/v1/agents/:slug/run
Execute an agent with custom input parameters.
{
"input": {
// Agent-specific parameters
},
"wait_for_completion": false // Optional: true to wait for result (max 60s)
}
{
"job_id": 12345,
"status": "pending",
"message": "Job created successfully",
"created_at": "2026-01-25T16:00:00Z",
"check_status": "/api/v1/jobs/12345"
}
/api/v1/jobs/:id
Check the status and result of a job.
{
"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"
}
/api/v1/agents
Get list of available agents you can invoke.
category - Filter by category (optional)search - Search by name or description (optional)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'
});
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'
})
Get notified when jobs complete instead of polling. Configure webhooks in your dashboard.
{
"event": "job.completed", // or "job.failed"
"job_id": 12345,
"status": "completed",
"output": { /* result data */ },
"completed_at": "2026-01-25T16:00:05Z"
}
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;
}
| 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 |
Check out our examples or reach out to support.