Noesis / API Reference

Analyse a call recording

POST/v1/detect/file

Analyses a recorded call as if it were live and returns the answer. Send a WAV file (PCM, float or G.711; 1 second to 15 minutes, at most 50 MB) as multipart/form-data in the file field, or as the request body. Options as query parameters or form fields: call_id, language, remote_channel (stereo files), transcripts (default true), record (false to not keep the recording). The file is replayed in real time, so the answer takes about as long as the recording: the response (200) starts at once, sends a newline every few seconds to keep the connection open, and ends with one JSON object, the result (type: result) or {"type":"error",...} if the analysis failed (then nothing is charged). File analyses use your account balance. Send an Idempotency-Key to make retries safe (24 h). Requires scope noesis:detect.

Authentication

Send your API key as Authorization: Bearer <your API key>.

Headers

Name	Type	Details
`Authorization`required	string	`Bearer <your API key>`. Keys are created in the dashboard; see Authentication.
`Idempotency-Key`optional	string or null	Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again. 1 to 128 characters

Request body

Send the request as multipart/form-data. Upload the recording as a WAV file in the file field (up to 50 MB and 15 minutes) and send the other fields as form fields. See Recorded calls.

filefilerequired
The WAV file (PCM, float or G.711; 1 s to 15 min; at most 50 MB).
call_idstring
Your id for the call.

at most 200 characters
languagestring
Language hint, e.g. en or hi.

at most 16 characters
remote_channelinteger
Stereo files: the channel of the person called.

default 0One of: 0, 1
transcriptsboolean
Include the transcript.

default true
recordboolean
Keep the recording and transcript for 30 days; false to not keep them.

default true

Response

200 The analysis runs: newlines while it works, then one JSON object (this result, or {"type":"error","code","error","status"}).

typestringrequired
always "result"
session_idstringrequired
call_idstring or null
fileobjectrequired
firstobject or nullrequired
finalobject or nullrequired
timelinearray of objectrequired
transcriptarray of object or null
usageobject or null
operation_idstringrequired
billed_secondsnumberrequired
creditsobject or null
What the analysis used from your balance.
idempotent_replaybooleanrequired

Example response

JSON

{
  "type": "result",
  "session_id": "5b2f0c9e8d7a4b6c9e1f2a3b4c5d6e7f",
  "call_id": "crm-4711",
  "file": {
    "name": "call.wav",
    "duration_s": 42.5,
    "format": "pcm_s16le",
    "sample_rate": 8000,
    "channels": 1
  },
  "first": {
    "label": "voicemail",
    "category": "machine",
    "confidence": 0.88,
    "t": 3.1
  },
  "final": {
    "label": "voicemail",
    "category": "machine",
    "confidence": 0.95
  },
  "timeline": [
    {
      "seq": 1,
      "t": 3.1,
      "label": "voicemail",
      "category": "machine",
      "confidence": 0.88,
      "change": "initial",
      "reason": "A greeting asks to leave a message."
    }
  ],
  "transcript": [
    {
      "t": 0.8,
      "text": "Hi, you've reached Ada. Leave a message."
    }
  ],
  "usage": {
    "audio_s": 42.5,
    "transcribed_s": 42.5,
    "checks": 3
  },
  "operation_id": "op_6f1ed002ab5595859014ebf0951522d9",
  "billed_seconds": 42.5,
  "idempotent_replay": false
}

Errors

Status	Meaning
400	The request is invalid, for example an API key in the URL or an unsupported parameter.
401	The API key is missing, invalid or revoked.
402	Your balance is too low for this call or file.
403	The key lacks the required scope, the e-mail address is not verified, or the account is suspended.
408	The upload did not arrive in time.
409	A request with the same Idempotency-Key is still running.
413	The file is larger than 50 MB.
415	Not a WAV file.
422	The recording is too short or too long, or the Idempotency-Key was used for a different request.
429	Too many requests, or too many calls and file analyses at the same time. Wait for Retry-After seconds.
500	Something went wrong on our side.
503	Noesis is busy or temporarily unavailable. Retry after the Retry-After seconds.

Error bodies share one shape with a stable error.code; see Errors for every code and how to fix it.

Code samples

cURL

curl "https://api.noesis.detectif.ai/v1/detect/file" \
  -H "Authorization: Bearer $DETECTIF_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@call.wav"

Python

import os
import uuid

import requests

with open("call.wav", "rb") as f:
    resp = requests.post(
        "https://api.noesis.detectif.ai/v1/detect/file",
        headers={"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
        files={"file": f},
        timeout=300,
    )
print(resp.status_code, resp.json())

JavaScript

import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const form = new FormData();
form.append("file", new Blob([await readFile("call.wav")]), "call.wav");

const res = await fetch("https://api.noesis.detectif.ai/v1/detect/file", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DETECTIF_API_KEY}`,
    "Idempotency-Key": randomUUID(),
  },
  body: form,
});
console.log(res.status, await res.json());

#Authentication

#Headers

#Request body

#Response

#Example response

#Errors

#Code samples