ConductSpeech

For developers · Research-tier integrations

API Documentation

Research accounts can run batch analysis and export over REST with an API key. This page documents the two endpoints a key opens.

Authentication

Send your API key in the X-API-Key header. Research accounts generate keys in Settings → API Keys. Keys are shown once and stored as SHA-256 hashes. If you lose a key, revoke it and generate a new one. A key can stop working when ConductSpeech is updated: if a call answers 401 with a key that worked before, generate a new one.

curl -X POST https://engine.conductspeech.com/batch/analyze \
  -H "X-API-Key: csp_..." \
  -H "Content-Type: application/json" \
  -d '{"items": [{"itemId": "s1", "ageMonths": 48, "utterances": [...]}]}'

Base URL

https://engine.conductspeech.com

Endpoints

POST/batch/analyze

Analyze up to 1,000 samples in one request. Each utterance needs index, speaker (child or examiner) and text. The fields morphemes, morphemeCount, wordCount, isGrammatical and errors must be present; every count is made again from the text. An optional metadata object (for example a group column) is kept with each item.

Request

{
  "items": [
    { "itemId": "s1", "label": "Pre-test", "ageMonths": 48,
      "metadata": { "group": "A" },
      "utterances": [
        { "index": 0, "speaker": "child", "text": "the dog runs",
          "morphemes": [], "morphemeCount": 0, "wordCount": 0,
          "isGrammatical": true, "errors": [] },
        ...
      ] },
    { "itemId": "s2", "label": "Post-test", "ageMonths": 60,
      "metadata": { "group": "A" }, "utterances": [ ... ] }
  ]
}

Response

{
  "summary": { "total": 2, "succeeded": 2, "failed": 0,
               "meanMluMorphemes": 7.75, "meanTtr": 0.8875, "errors": [],
               "cohorts": [ { "group": "A", "n": 2, "meanMluMorphemes": 7.75, ... } ] },
  "items": [
    { "itemId": "s1", "label": "Pre-test", "ageMonths": 48, "metadata": { "group": "A" },
      "metrics": { "mluMorphemes": 4.5, "mluWords": 4.0, "ttr": 0.875, "ndw": 7, ... },
      "advanced": { "dss": ..., "ipsyn": ..., ... },
      "normative": { "status": "within", "expectedRange": [3.81, 5.33], "zScore": -0.09,
        "ageBand": "4;0 to 4;5", "sampleSize": 49, "source": "Rice et al. (2010)", ... },
      "error": null },
    ...
  ]
}
POST/batch/export

Export the items of a batch answer as CSV, SPSS syntax, SAS syntax, or a Python notebook.

Request

{
  "items": [ ... ],         // the items of a /batch/analyze answer
  "format": "spss"         // csv | spss | sas | notebook
}

Response

{
  "format": "spss",
  "csvFilename": "conductspeech_export.csv",
  "csv": "itemId,label,ageMonths,group,...\n...",
  "syntax": "* SPSS syntax generated by ConductSpeech.\n...",
  "syntaxFilename": "conductspeech_import.sps"
}

Errors

Errors return an HTTP status code plus a JSON body with a detail field.

  • 400: no items, or an export format other than csv, spss, sas or notebook
  • 401: missing or invalid API key
  • 413: more than 1,000 samples in one batch
  • 422: a request body that does not match the shape above