API Reference

The Auralis Cloud API lets you integrate job submission and management into your applications.

Base URL: https://auraliscloud.xyz/api

Authentication

Most endpoints require authentication. Include your user ID as a query parameter or in the request body.

Worker endpoints use Bearer token authentication:

Authorization: Bearer aw_your_token_here

Job Endpoints

Submit a Job

Upload a project and create a new job.

POST /api/upload
Content-Type: multipart/form-data

Parameters:

Field	Type	Required	Description
`user_id`	string	Yes	Your user ID
`file`	file	Yes	.zip or .tar of your project
`platform`	string	No	`linux/amd64` or `linux/arm64` (default: amd64)
`timeout`	int	No	Max runtime in hours (default: 8)
`output_directory`	string	No	Output path in container (default: ./output)

Response:

{
  "status": "success",
  "message": "Job created successfully",
  "job_id": "abc-123-def",
  "input_url": "s3://..."
}

List Your Jobs

Get all jobs for a user.

GET /api/jobs?user_id=YOUR_USER_ID

Response:

[
  {
    "id": "abc-123",
    "status": "COMPLETED",
    "platform": "linux/amd64",
    "timeout": 2,
    "created_at": "2025-12-14T10:00:00Z",
    "completed_at": "2025-12-14T10:30:00Z"
  }
]

Get Job Details

Get details for a specific job.

GET /api/jobs/{job_id}

Response:

{
  "id": "abc-123",
  "user_id": "user-456",
  "status": "COMPLETED",
  "input_url": "s3://...",
  "output_url": "s3://...",
  "platform": "linux/amd64",
  "timeout": 2,
  "created_at": "2025-12-14T10:00:00Z",
  "started_at": "2025-12-14T10:05:00Z",
  "completed_at": "2025-12-14T10:30:00Z"
}

Get Pending Jobs

List available jobs (for providers).

GET /api/jobs/pending?platform=linux/amd64

Parameters:

Field	Type	Description
`platform`	string	Filter by platform

Download Job Output

Get a presigned URL to download job outputs.

GET /api/jobs/{job_id}/download-url

Response:

{
  "download_url": "https://s3.amazonaws.com/..."
}

Worker Endpoints

These endpoints are used by the worker CLI.

Register a Worker

POST /api/worker/register
Content-Type: application/json

Body:

{
  "user_id": "user-123",
  "name": "My Worker",
  "platform": "linux/amd64"
}

Response:

{
  "worker_id": "worker-456",
  "token": "aw_abc123...",
  "name": "My Worker",
  "platform": "linux/amd64"
}

Save the token! It's only shown once.

Get Available Jobs (Authenticated)

GET /api/worker/jobs/available
Authorization: Bearer YOUR_TOKEN

Returns jobs matching your worker's platform.

Claim a Job

POST /api/worker/job/{job_id}/claim
Authorization: Bearer YOUR_TOKEN

Update Job Status

POST /api/worker/job/{job_id}/status
Authorization: Bearer YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

status=RUNNING

Valid statuses: RUNNING, COMPLETED, FAILED

Job Statuses

Status	Description
`PENDING`	Waiting for a worker
`CLAIMED`	Worker has claimed it
`RUNNING`	Currently executing
`COMPLETED`	Finished successfully
`FAILED`	Something went wrong

Rate Limiting

API requests are rate-limited to prevent abuse:

100 requests per minute per user
Returns 429 Too Many Requests if exceeded
Retry-After header indicates when to retry

Becoming a Provider Platform Requirements