API Reference¶

django-ray is a library that provides a Django Tasks backend and supported, versioned Python observability services. It does not prescribe a REST framework or mount a general REST API. The HTTP endpoints below are part of the testproject and adapt the package services with Django Ninja and bearer authentication.

What django-ray Provides¶

django-ray provides:

• RayTaskBackend - Django Tasks backend
• RayTaskExecution model - Task execution tracking
• TaskWorkerLease model - Worker coordination
• django_ray_worker management command - Task processing
• Django Admin integration - Task monitoring
• Versioned task, queue, attempt, workflow, and live-Ray observability services
• Reusable bounded-cardinality Prometheus rendering

testproject API (Example Only)¶

The testproject in this repository includes a REST API built with Django Ninja to demonstrate django-ray functionality. This API is not part of the django-ray package.

If you need a REST API for task management in your project, you can use the testproject as a reference implementation.

Example Endpoints (testproject)¶

⚠️ Note: These endpoints are from the testproject, not the django-ray library.

When the testproject server is running: - Swagger UI: http://localhost:8000/api/docs - OpenAPI Schema: http://localhost:8000/api/openapi.json

Building Your Own API¶

To add task management endpoints to your project, query the django-ray models directly:

from django.db.models import Count

from django_ray.models import RayTaskExecution, TaskState

# List executions
executions = RayTaskExecution.objects.filter(state=TaskState.QUEUED)

# Get stats
stats = RayTaskExecution.objects.values("state").annotate(count=Count("id"))


def request_cancellation(execution_id: int) -> None:
    execution = RayTaskExecution.objects.get(pk=execution_id)
    if execution.state == TaskState.QUEUED:
        execution.state = TaskState.CANCELLED
    elif execution.state == TaskState.RUNNING:
        execution.state = TaskState.CANCELLING
    else:
        return
    execution.save(update_fields=["state"])

For a complete REST API example, see testproject/api.py in the repository.

The reusable helpers in django_ray.observability expose schema-versioned task, queue, attempt, and workflow snapshots, then optionally query Ray's live State and Log APIs. The bounded functions in django_ray.workflow_progress_reads expose summary, topology-node, topology-edge, node-detail, and indexed-node reads. Every call requires an object authorizer; applications must replace the testproject's callable allowlist with their tenant or ownership policy. django_ray.metrics.render_prometheus_metrics() supplies the package-owned text format used by the sample endpoint. Treat node logs and operational metadata as sensitive.

The indexed example accepts node_id as a query parameter so URL encoding round-trips the full bounded UTF-8 identifier, including values such as namespace/apply. The older /nodes/{node_id} route retains its live-Ray and optional-log behavior for testproject compatibility; it is not the normalized indexed read facade.

See Observability Services for the supported Python schemas, metrics, degradation behavior, and security boundary.

See Also¶

• Getting Started - Basic setup
• Tasks - Defining tasks