Cognitive Signal Analysis — POST /v1/analyze/cognitive

The POST /v1/analyze/cognitive endpoint accepts an audio file and returns a JSON object containing cognitive signals extracted from the recording. This endpoint requires Bearer token authentication.

Endpoint

POST https://api.dolva.ai/v1/analyze/cognitive

Authentication

This endpoint requires a Bearer token. Include it in the Authorization header:

Authorization: Bearer dv-xxxxxxxx

Request

Content-Type: multipart/form-data

Request Fields

file

required

The audio file to analyze. Supported formats include WAV, MP3, M4A, FLAC, and OGG. See Audio Requirements for details.

Response

Status: 200 OK
Content-Type: application/json The response is a JSON object. The exact fields returned depend on the analysis model and may vary; the API spec defines the response as a free-form JSON object (additionalProperties: true). The following example illustrates the shape of a typical response:

200 OK

{
  "status": "ok",
  "signals": {
    "cognitive_load": 0.72,
    "clarity": 0.85
  }
}

Example Response Fields

The fields below are illustrative examples of what the response may contain. Refer to the Dolva dashboard or model release notes for the authoritative list of fields returned by your model version.

string

An example status indicator. May be "ok" on a successful analysis.

object

An example wrapper object containing extracted cognitive signals.

Show signals properties

number

An example score from 0.0 to 1.0 representing the detected level of cognitive load. Higher values indicate greater mental effort.

number

An example score from 0.0 to 1.0 representing the clarity and organization of speech. Higher values indicate clearer thinking patterns.

Error Responses

Status	Description
`401 Unauthorized`	Bearer token is missing or invalid
`422 Unprocessable Entity`	The `audio` field is missing or the file is invalid

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "audio"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Code Examples

curl -X POST https://api.dolva.ai/v1/analyze/cognitive \
  -H "Authorization: Bearer dv-xxxxxxxx" \
  -F "audio=@recording.wav"

import requests
import os

with open("recording.wav", "rb") as f:
    response = requests.post(
        "https://api.dolva.ai/v1/analyze/cognitive",
        headers={"Authorization": f"Bearer {os.environ['DOLVA_API_TOKEN']}"},
        files={"audio": f}
    )

print(response.json())

import fetch from "node-fetch";
import FormData from "form-data";
import fs from "fs";

const form = new FormData();
form.append("audio", fs.createReadStream("recording.wav"));

const response = await fetch("https://api.dolva.ai/v1/analyze/cognitive", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DOLVA_API_TOKEN}`,
    ...form.getHeaders(),
  },
  body: form,
});

console.log(await response.json());

​Endpoint

​Authentication

​Request

​Request Fields

​Response

​Example Response Fields

​Error Responses

​Code Examples