Make your first request

What to send

Send your file with your API key. Replace YOUR_FILE.pdf with its path. No Steletta library is needed.

The same three requests work for every PDF or Word (.docx) file up to 20 MiB: prepare the upload, send the file, then start the review. Steletta handles the file type, size and checksum.

Set your key in the terminal before running the example:

Terminal

export STELETTA_API_KEY="YOUR_API_KEY"

cURL uses jq to read the JSON response. Python uses requests. JavaScript uses Node.js 20+ with no extra packages.

What you get back

A review ID and its initial status. The review runs in the background. Save the ID to check status, then retrieve the finished report.

This runs a real review and uses your organization's allowance. Each fresh run submits a new review. Failed or cancelled reviews use no review units.

Upload a file and start a review

set -e
base="https://www.steletta.com/api/v1"
file="YOUR_FILE.pdf"

# 1. Prepare the upload
upload=$(curl --fail-with-body "$base/uploads" \
  -H "Authorization: Bearer $STELETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg filename "$(basename "$file")" '{filename:$filename}')")
upload_id=$(printf '%s' "$upload" | jq -er '.id')
upload_url=$(printf '%s' "$upload" | jq -er '.uploadUrl')
content_type=$(printf '%s' "$upload" | jq -er '.uploadHeaders["Content-Type"]')

# 2. Send the file
status=$(curl --fail-with-body -X PUT "$upload_url" \
  -H "Content-Type: $content_type" \
  --data-binary "@$file" -o /dev/null -w '%{http_code}')
case "$status" in 2??) ;; *) exit 1 ;; esac

# 3. Start the review
curl --fail-with-body -X POST "$base/uploads/$upload_id/complete" \
  -H "Authorization: Bearer $STELETTA_API_KEY"

Example response

{
  "review": {
    "id": "rev_example",
    "status": "queued",
    "createdAt": "2026-09-29T14:00:00Z",
    "completedAt": null,
    "usage": {
      "estimatedUnitsMilli": 1000,
      "finalUnitsMilli": null
    },
    "error": null
  },
  "replayed": false
}

Add context when useful

The optional purpose field accepts your title, description, learning goals or other relevant context. Labels and formatting are up to you. See the request fields and context example.

If completion fails temporarily, retry it with the saved upload ID. For retries of the prepare request, see safe retries. These examples create a new upload each time they run.