API Documentation — myQA.team

CaptureIQ

POST/api/v1/captureiq/analyze

Analyze an audio recording or transcript and receive a structured list of observations (nonconformities, decisions, action items, etc.). Supports both audit and meeting session types.

Authentication

Requires captureiq:analyze permission. See Authentication.

Request — multipart — audio

1curl -X POST https://api.myqateam.com/api/v1/captureiq/analyze \
2  -H "Authorization: Bearer myqa_..." \
3  -F "audio=@recording.mp3" \
4  -F "session_type=audit"

Request — JSON — transcript

1curl -X POST https://api.myqateam.com/api/v1/captureiq/analyze \
2  -H "Authorization: Bearer myqa_..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "transcript": "Auditor: Walk me through your cold-chain procedure...",
6    "session_type": "audit"
7  }'

Request — Google Cloud Storage reference

Instead of uploading the recording, reference one you already hold in Cloud Storage. Recommended for long recordings: the audio is read directly from storage and never travels through the API request.

json

1{
2  "gcs_uri": "gs://your-bucket/meetings/2026-08-07.mp3",
3  "session_type": "meeting",
4  "callback_url": "https://yourdomain.com/webhooks/captureiq"
5}

Requires a one-time setup: grant the Storage Object Viewer role on your bucket to the service account we provide, and tell us the bucket name so it can be registered against your API key. References to buckets that are not registered are refused with 403 FORBIDDEN.

Fields

Field	Type	Required	Description
`audio`	File	Either/or	Audio file (MP3, WAV, AAC, FLAC, OGG, WebM, M4A, MP4). Max 2 GB.
`gcs_uri`	string	Either/or	`gs://bucket/object` reference to the recording. The bucket must be registered against your API key.
`transcript`	string	Either/or	Raw transcript text.
`mime_type`	string	No	Content type of the referenced object. Inferred from the file extension when omitted.
`session_type`	enum	No	`audit` (default) or `meeting`.
`callback_url`	string	No	HTTPS webhook. If set, the API returns a job ID immediately. Must be HTTPS and must not target localhost / private (RFC1918) / link-local IPs, or cloud-metadata services.
`callback_secret`	string	No	HMAC-SHA256 secret used to sign the webhook payload.

Response — synchronous

json

1{
2  "success": true,
3  "data": {
4    "session_type": "audit",
5    "transcript": "...",
6    "summary": "...",
7    "observations": [
8      {
9        "content": "Cold-storage logs show a 2°C excursion on 2026-04-12 that was not escalated.",
10        "category": "nonconformity",
11        "display_order": 1
12      }
13    ],
14    "language": "en",
15    "processing_time_ms": 45000,
16    "token_usage": { "input_tokens": 500, "output_tokens": 1200 }
17  }
18}

Observation categories

Each observation is tagged with one of the following categories. The set depends on session_type; any unrecognised category returned by the model is normalised to general_note.

`session_type`	Allowed categories
`audit`	`nonconformity`, `opportunity_for_improvement`, `positive_finding`, `action_item`, `general_note`
`meeting`	`decision`, `key_point`, `follow_up`, `action_item`, `general_note`

Response — async acknowledgement

json

1{
2  "success": true,
3  "data": {
4    "job_id": "c4b2…",
5    "status": "processing",
6    "estimated_duration_sec": 120
7  }
8}

Webhook payload

When the job completes we send an HTTP POST to your callback_url with Content-Type: application/json. The body is the JSON object shown below. If you supplied a callback_secret, the request also carries an X-Webhook-Signature header whose value is the HMAC-SHA256 of the raw request body. Webhook deliveries are best-effort and not retried — we record every attempt with the response status, duration, and any error.

We do not send a Bearer token to your endpoint. Either verify theX-Webhook-Signature header using callback_secret, or include a hard-to-guess token in the URL itself (e.g. https://example.com/webhooks/captureiq/<random-token>).

Successful job payload

json

1{
2  "job_id": "c4b2…",
3  "success": true,
4  "data": {
5    "session_type": "audit",
6    "transcript": "…",
7    "summary": "…",
8    "observations": [ /* same shape as the sync response */ ],
9    "language": "en",
10    "processing_time_ms": 45000,
11    "token_usage": { "input_tokens": 500, "output_tokens": 1200 }
12  }
13}

Failed job payload

json

1{
2  "job_id": "c4b2…",
3  "success": false,
4  "error": { "code": "PROCESSING_ERROR", "message": "…" }
5}

Your endpoint should respond with 2xx within ~10 seconds; non-2xx responses are recorded but not retried.

1import crypto from 'node:crypto'
2
3const expected = crypto
4  .createHmac('sha256', process.env.CAPTUREIQ_SECRET)
5  .update(rawBody)
6  .digest('hex')
7
8if (expected !== req.headers['x-webhook-signature']) {
9  return res.status(401).send('bad signature')
10}

Errors

See the full error code reference on the authentication page.