API Reference

1. Get Your API Key

Generate an API key from your dashboard. API keys start with rird_ and provide programmatic access.

2. Submit Your First Task

curl -X POST https://rird.ai/api/cloud/tasks \
  -H "Authorization: Bearer rird_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find 10 software companies on LinkedIn"
  }'

Payload Format

{
  "event": "task.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "task": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "Find 50 contractors on SAM.gov",
    "status": "completed",
    "result": { ... },
    "resultSummary": "Found 50 contractors",
    "startedAt": "2025-01-15T10:31:00Z",
    "completedAt": "2025-01-15T10:35:00Z",
    "processingTimeMs": 240000
  }
}

Signature Verification

Verify webhook authenticity using the X-RIRD-Signature header:

// Node.js example
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHash('sha256')
    .update(payload + secret)
    .digest('hex');
  return signature === expected;
}

// In your webhook handler
app.post('/webhooks/rird', (req, res) => {
  const signature = req.headers['x-rird-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  console.log('Task completed:', req.body.task.id);
  res.status(200).send('OK');
});

Webhook Headers

• X-RIRD-Signature - HMAC signature for verification
• X-RIRD-Timestamp - Event timestamp (ISO 8601)
• X-RIRD-Event - Event type (task.completed, etc.)

JavaScript / Node.js

const RIRD_API_KEY = 'rird_your_api_key';

async function runTask(prompt) {
  const response = await fetch('https://rird.ai/api/cloud/tasks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${RIRD_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt })
  });
  return response.json();
}

async function getTask(taskId) {
  const response = await fetch(`https://rird.ai/api/cloud/tasks/${taskId}`, {
    headers: { 'Authorization': `Bearer ${RIRD_API_KEY}` }
  });
  return response.json();
}

// Usage
const { task } = await runTask('Find 10 tech companies in NYC');
console.log('Task submitted:', task.id);

// Poll for completion
let result;
do {
  await new Promise(r => setTimeout(r, 5000));
  result = await getTask(task.id);
} while (result.task.status === 'queued' || result.task.status === 'processing');

console.log('Result:', result.task.resultSummary);

Python

import requests
import time

RIRD_API_KEY = 'rird_your_api_key'
BASE_URL = 'https://rird.ai/api'

def run_task(prompt: str, webhook_url: str = None):
    response = requests.post(
        f'{BASE_URL}/cloud/tasks',
        headers={'Authorization': f'Bearer {RIRD_API_KEY}'},
        json={'prompt': prompt, 'webhook_url': webhook_url}
    )
    return response.json()

def get_task(task_id: str):
    response = requests.get(
        f'{BASE_URL}/cloud/tasks/{task_id}',
        headers={'Authorization': f'Bearer {RIRD_API_KEY}'}
    )
    return response.json()

def wait_for_completion(task_id: str, poll_interval: int = 5):
    while True:
        result = get_task(task_id)
        status = result['task']['status']
        if status in ('completed', 'failed'):
            return result
        time.sleep(poll_interval)

# Usage
result = run_task('Scrape the top 20 products from ProductHunt')
task_id = result['task']['id']
print(f'Task submitted: {task_id}')

final = wait_for_completion(task_id)
print(f'Result: {final["task"]["resultSummary"]}')