REST API

STDWeb provides a REST API for programmatic access to image processing functionality.

For complete API documentation with examples, see the REST API Reference.

Authentication

The API uses token-based authentication. Obtain a token:

curl -X POST /api/auth/token/ \
  -d "username=<username>&password=<password>"

Include the token in subsequent requests:

curl -H "Authorization: Token <your-token>" /api/tasks/

Creating API Tokens

# Via management command
python manage.py drf_create_token <username>

# Or via Django shell
python manage.py shell
>>> from rest_framework.authtoken.models import Token
>>> from django.contrib.auth.models import User
>>> user = User.objects.get(username='myuser')
>>> token, created = Token.objects.get_or_create(user=user)
>>> print(token.key)

Main Endpoints

Tasks

Endpoint	Description
`GET /api/tasks/`	List tasks for current user
`POST /api/tasks/`	Create new task with file upload
`GET /api/tasks/{id}/`	Get task details
`PATCH /api/tasks/{id}/`	Update task configuration
`DELETE /api/tasks/{id}/`	Delete task and files
`POST /api/tasks/{id}/duplicate/`	Duplicate task

Processing

Endpoint	Description
`POST /api/tasks/{id}/process/`	Start processing steps
`POST /api/tasks/{id}/cancel/`	Cancel running task

Available processing steps: cleanup, inspect, photometry, simple_transients, subtraction

Files

Endpoint	Description
`GET /api/tasks/{id}/files/`	List task files
`GET /api/tasks/{id}/files/{path}`	Download file
`POST /api/tasks/{id}/files/{path}`	Upload file
`DELETE /api/tasks/{id}/files/{path}`	Delete file
`GET /api/tasks/{id}/preview/{path}`	Generate FITS preview image

Queue

Endpoint	Description
`GET /api/queue/`	List Celery queue status
`GET /api/queue/{celery_id}/`	Get task status
`POST /api/queue/{celery_id}/terminate/`	Terminate task (staff only)

Reference Data

Endpoint	Description
`GET /api/reference/`	List all reference data
`GET /api/reference/filters/`	Available photometric filters
`GET /api/reference/catalogs/`	Available reference catalogs
`GET /api/reference/templates/`	Available template sources
`GET /api/presets/`	List configuration presets

Quick Example

# Get token
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/token/ \
  -d "username=myuser&password=mypass" | jq -r .token)

# Upload and create task
TASK_ID=$(curl -s -X POST http://localhost:8000/api/tasks/ \
  -H "Authorization: Token $TOKEN" \
  -F "file=@image.fits" \
  -F 'config={"filter":"R"}' | jq -r .id)

# Run processing
curl -X POST "http://localhost:8000/api/tasks/$TASK_ID/process/" \
  -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"steps":["inspect","photometry"]}'

# Check status
curl "http://localhost:8000/api/tasks/$TASK_ID/" \
  -H "Authorization: Token $TOKEN"

Python Client

import requests

BASE_URL = "http://localhost:8000/api"

# Authenticate
response = requests.post(f"{BASE_URL}/auth/token/",
    data={"username": "myuser", "password": "mypass"})
token = response.json()["token"]

session = requests.Session()
session.headers["Authorization"] = f"Token {token}"

# Upload file
with open("image.fits", "rb") as f:
    response = session.post(f"{BASE_URL}/tasks/",
        files={"file": f},
        data={"config": '{"filter": "R"}'})
task_id = response.json()["id"]

# Process
session.post(f"{BASE_URL}/tasks/{task_id}/process/",
    json={"steps": ["inspect", "photometry"]})

# Get results
task = session.get(f"{BASE_URL}/tasks/{task_id}/").json()
print(f"Zero point: {task['config'].get('zp')}")