> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dolva.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cognitive Signal Analysis — POST /v1/analyze/cognitive

> Upload an audio file to extract cognitive signals such as cognitive load and speech clarity. Requires Bearer auth and multipart/form-data encoding.

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

```text theme={null}
POST https://api.dolva.ai/v1/analyze/cognitive
```

## Authentication

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

```text theme={null}
Authorization: Bearer dv-xxxxxxxx
```

## Request

**Content-Type:** `multipart/form-data`

### Request Fields

<ParamField body="audio" type="file" required>
  The audio file to analyze. Supported formats include WAV, MP3, M4A, FLAC, and OGG. See [Audio Requirements](/concepts/audio-requirements) for details.
</ParamField>

## 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:

```json 200 OK theme={null}
{
  "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.

<ResponseField name="status" type="string">
  An example status indicator. May be `"ok"` on a successful analysis.
</ResponseField>

<ResponseField name="signals" type="object">
  An example wrapper object containing extracted cognitive signals.

  <Expandable title="signals properties">
    <ResponseField name="cognitive_load" type="number">
      An example score from `0.0` to `1.0` representing the detected level of cognitive load. Higher values indicate greater mental effort.
    </ResponseField>

    <ResponseField name="clarity" type="number">
      An example score from `0.0` to `1.0` representing the clarity and organization of speech. Higher values indicate clearer thinking patterns.
    </ResponseField>
  </Expandable>
</ResponseField>

## 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 |

```json 422 Validation Error theme={null}
{
  "detail": [
    {
      "loc": ["body", "audio"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Code Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.dolva.ai/v1/analyze/cognitive \
    -H "Authorization: Bearer dv-xxxxxxxx" \
    -F "audio=@recording.wav"
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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());
  ```
</CodeGroup>