API Reference

curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "my-queue",
    "payload": {
      "event": "user.created",
      "user_id": "usr_123",
      "email": "alice@example.com"
    },
    "idempotency_key": "user-created-usr_123"
  }'

import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

const userId = 'usr_123';

// Create a job
const { id } = await client.jobs.create({
  queueName: 'email-notifications',
  payload: {
    to: 'user@example.com',
    subject: 'Welcome!',
    template: 'welcome',
  },
  idempotencyKey: `welcome-${userId}`,
  maxRetries: 5,
});

console.log(`Created job: ${id}`);

from spooled import SpooledClient
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

image_id = "img_123"

# Create a background job
result = client.jobs.create({
    "queue_name": "image-processing",
    "payload": {
        "image_url": "https://example.com/image.jpg",
        "operations": ["resize", "compress"],
        "output_format": "webp"
    },
    "idempotency_key": f"process-image-{image_id}",
    "max_retries": 3
})

print(f"Created job: {result.id}")

client.close()

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

func ptr[T any](v T) *T { return &v }

func main() {
	client, err := spooled.NewClient(spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")))
	if err != nil {
		panic(err)
	}

	resp, err := client.Jobs().Create(context.Background(), &resources.CreateJobRequest{
		QueueName:      "my-queue",
		Payload:        map[string]any{"key": "value"},
		IdempotencyKey: ptr("unique-key"),
		MaxRetries:     ptr(3),
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Created job: %s\n", resp.ID)
}

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

$userId = 'usr_123';

// Create a job
$job = $client->jobs->create([
    'queue' => 'email-notifications',
    'payload' => [
        'to' => 'user@example.com',
        'subject' => 'Welcome!',
        'template' => 'welcome',
    ],
    'idempotencyKey' => "welcome-{$userId}",
    'maxRetries' => 5,
]);

echo "Created job: {$job->id}\n";

# Claim up to 5 jobs
curl -X POST https://api.spooled.cloud/api/v1/jobs/claim \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_name": "my-queue",
    "worker_id": "worker-1",
    "limit": 5
  }'

// Claim jobs for processing
const { jobs } = await client.jobs.claim({
  queueName: 'my-queue',
  workerId: 'worker-1',
  limit: 10,
  leaseDurationSecs: 30,
});

for (const job of jobs) {
  console.log(`Claimed job: ${job.id}`);
  // Process the job...
}

# Claim jobs for processing
result = client.jobs.claim({
    "queue_name": "my-queue",
    "worker_id": "worker-1",
    "limit": 10,
    "lease_duration_secs": 30
})

for job in result.jobs:
    print(f"Claimed job: {job.id}")
    # Process the job...

import (
	"github.com/spooled-cloud/spooled-sdk-go/spooled/types"
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

client, _ := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

claimed, err := client.Jobs().Claim(context.Background(), &resources.ClaimJobsRequest{
	QueueName: "my-queue",
	WorkerID:  "worker-1",
	Limit:     types.Int(10),
})
if err != nil {
	panic(err)
}

for _, job := range claimed.Jobs {
	fmt.Printf("Claimed job: %s\n", job.ID)
}

<?php

// Claim jobs for processing
$result = $client->jobs->claim([
    'queue' => 'my-queue',
    'workerId' => 'worker-1',
    'limit' => 10,
    'leaseDurationSecs' => 30,
]);

foreach ($result->jobs as $job) {
    echo "Claimed job: {$job->id}\n";
    // Process the job...
}

# Complete a job (echo lease_id from the claim response)
curl -X POST https://api.spooled.cloud/api/v1/jobs/job_xyz123/complete \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "worker_id": "worker-1",
    "lease_id": "lease_abc",
    "result": {"processed": true}
  }'

// Complete the job after processing (echo leaseId from claim)
await client.jobs.complete(job.id, {
  workerId: 'worker-1',
  leaseId: job.leaseId ?? undefined,
  result: { processed: true, outputUrl: 'https://...' },
});

# Complete the job after processing (echo lease_id from claim)
client.jobs.complete(job.id, {
    "worker_id": "worker-1",
    "lease_id": job.lease_id,
    "result": {"processed": True, "output_url": "https://..."}
})

import (
	"github.com/spooled-cloud/spooled-sdk-go/spooled/types"
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/resources"
)

client, _ := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

err := client.Jobs().Complete(context.Background(), job.ID, &resources.CompleteJobRequest{
	WorkerID: "worker-1",
	LeaseID:  job.LeaseID,
	Result:   map[string]interface{}{"processed": true, "output_url": "https://..."},
})
if err != nil {
	panic(err)
}

fmt.Println("Job completed successfully")

<?php

// Complete the job after processing (echo leaseId from claim)
$client->jobs->complete($job->id, [
    'workerId' => 'worker-1',
    'leaseId' => $job->leaseId,
    'result' => ['processed' => true, 'outputUrl' => 'https://...'],
]);

# All API requests require authentication
curl -X POST https://api.spooled.cloud/api/v1/jobs \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue_name": "my-queue", "payload": {...}}'

import { SpooledClient } from '@spooled/sdk';

// Initialize with API key from environment
const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// All subsequent calls are authenticated
const job = await client.jobs.create({...});

from spooled import SpooledClient
import os

# Initialize with API key from environment
client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

# All subsequent calls are authenticated
job = client.jobs.create({...})

# Don't forget to close the client
client.close()

import (
	"os"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
)

// Initialize with API key from environment
client, err := spooled.NewClient(
	spooled.WithAPIKey(os.Getenv("SPOOLED_API_KEY")),
)
if err != nil {
	panic(err)
}
defer client.Close()

// All subsequent calls are authenticated
job, _ := client.Jobs().Create(ctx, &resources.CreateJobRequest{
	QueueName: "emails",
	Payload:   map[string]any{"to": "user@example.com"},
})

<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

// Initialize with API key from environment
$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// All subsequent calls are authenticated
$job = $client->jobs->create([...]);