API Reference

Serverless API Reference

Complete API reference for submitting and managing serverless tasks.

Base URL

https://api.wavespeed.ai/serverless

Authentication

All requests require an API key:

Authorization: Bearer ${WAVESPEED_API_KEY}

Submit Task (Async)

Submit a task and receive a task ID immediately.

Endpoint

POST /v1/run

Request

curl --location --request POST 'https://api.wavespeed.ai/serverless/v1/run' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "endpoint": "my-endpoint",
    "input": {
        "prompt": "Hello, Waverless!"
    }
}'

Parameters

ParameterTypeRequiredDescription
endpointstringYesEndpoint name
inputobjectYesInput data for your handler
webhookstringNoURL to receive result via webhook

Response

{
    "id": "task_abc123",
    "status": "PENDING"
}

Submit Task (Sync)

Submit a task and wait for the result.

Endpoint

POST /v1/runsync

Request

curl --location --request POST 'https://api.wavespeed.ai/serverless/v1/runsync' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "endpoint": "my-endpoint",
    "input": {
        "prompt": "Hello, Waverless!"
    }
}'

Parameters

ParameterTypeRequiredDescription
endpointstringYesEndpoint name
inputobjectYesInput data for your handler
timeoutintegerNoMax wait time in seconds (default: 300)

Response

{
    "id": "task_abc123",
    "status": "COMPLETED",
    "output": {
        "result": "Processed: Hello, Waverless!"
    },
    "executionTime": 1500
}

Get Task Status

Check the status and result of a task.

Endpoint

GET /v1/status/{task_id}

Request

curl --location --request GET 'https://api.wavespeed.ai/serverless/v1/status/task_abc123' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}'

Response

{
    "id": "task_abc123",
    "status": "COMPLETED",
    "output": {
        "result": "Processed: Hello, Waverless!"
    },
    "executionTime": 1500,
    "createdAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:30:01Z"
}

Task Status Values

StatusDescription
PENDINGTask is queued, waiting for worker
IN_PROGRESSWorker is processing the task
COMPLETEDTask finished successfully
FAILEDTask failed (check error field)
CANCELLEDTask was cancelled

Cancel Task

Cancel a pending or in-progress task.

Endpoint

POST /v1/cancel/{task_id}

Request

curl --location --request POST 'https://api.wavespeed.ai/serverless/v1/cancel/task_abc123' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}'

Response

{
    "id": "task_abc123",
    "status": "CANCELLED"
}

List Workers

Get the list of online workers for an endpoint.

Endpoint

GET /v1/workers

Request

curl --location --request GET 'https://api.wavespeed.ai/serverless/v1/workers?endpoint=my-endpoint' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}'

Response

[
    {
        "id": "worker-001",
        "status": "ONLINE",
        "concurrency": 2,
        "currentJobs": 1,
        "endpoint": "my-endpoint"
    }
]

Worker Status Values

StatusDescription
ONLINEWorker is ready to accept tasks
BUSYWorker is at max concurrency
DRAININGWorker is shutting down gracefully
OFFLINEWorker is not connected

Error Responses

Error Format

{
    "error": {
        "code": "INVALID_REQUEST",
        "message": "Missing required field: endpoint"
    }
}

Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403No access to this endpoint
NOT_FOUND404Task or endpoint not found
INVALID_REQUEST400Invalid request parameters
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Server error

Webhooks

Receive task results via webhook instead of polling.

Setup

Include a webhook URL when submitting a task:

curl --location --request POST 'https://api.wavespeed.ai/serverless/v1/run' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "endpoint": "my-endpoint",
    "input": {"prompt": "Hello"},
    "webhook": "https://your-server.com/webhook"
}'

Webhook Payload

When the task completes, we POST to your webhook:

{
    "id": "task_abc123",
    "status": "COMPLETED",
    "output": {
        "result": "Processed: Hello"
    },
    "executionTime": 1500
}

Python Example

import os
import requests
import time
 
api_key = os.environ.get("WAVESPEED_API_KEY")
base_url = "https://api.wavespeed.ai/serverless"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
 
def submit_task(endpoint, input_data):
    """Submit async task."""
    response = requests.post(
        f"{base_url}/v1/run",
        headers=headers,
        json={"endpoint": endpoint, "input": input_data}
    )
    return response.json()
 
def get_status(task_id):
    """Get task status."""
    response = requests.get(
        f"{base_url}/v1/status/{task_id}",
        headers=headers
    )
    return response.json()
 
def wait_for_result(task_id, timeout=300):
    """Poll until task completes."""
    start = time.time()
    while time.time() - start < timeout:
        result = get_status(task_id)
        if result["status"] in ["COMPLETED", "FAILED", "CANCELLED"]:
            return result
        time.sleep(2)
    raise TimeoutError("Task timeout")
 
# Usage
task = submit_task("my-endpoint", {"prompt": "Hello"})
result = wait_for_result(task["id"])
print(result)

Related Pages

Build WorkerHow to Submit Task
© 2025 WaveSpeedAI. All rights reserved.