API reference

Public reference for posting recordings to the Shahed Detector pipeline. To use the API you need a bearer token, which you mint from Account → API tokens after signing in.

POST /api/ingest/recordings

Upload a single .wav recording. The server stores it, probes its duration and sample rate, and inserts a row in recordings with source: "api". Analysis is not run automatically — kick it off from the recordings UI or via a follow-up call.

Method

POST

URL

https://sound.cloud.teleporthq.ai/api/ingest/recordings

Auth header

Authorization: Bearer <token>

Body

multipart/form-data — single field file (a .wav, up to 100 MB)

Success

201 Created · JSON body with the new recording row

Errors

401 · missing or invalid bearer token

400 · missing file field, or file is not .wav

Example request

curl -X POST https://sound.cloud.teleporthq.ai/api/ingest/recordings \
  -H "Authorization: Bearer shd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "file=@/path/to/recording.wav"

Replace shd_xxxx… with a real token. Tokens are shown only once at creation time on the tokens page.

Example response

{
  "id": 42,
  "filename": "recording.wav",
  "storedPath": "/opt/project/data/uploads/...",
  "durationS": 38.4,
  "sampleRate": 16000,
  "sizeBytes": 1228844,
  "source": "api",
  "uploadedAt": "2026-05-23T08:00:00.000Z",
  "uploadedBy": "your-username"
}

The returned id is the recordings.id; uploads are also visible at /recordings/<id> in the web UI.