Upload Passage Audio - Plugixa Exam for WordPress

Upload Passage Audio - Plugixa Exam

POST /plugixa-exam/v1/passages/{id}/audio

Attach a recording to a passage, replacing the one it had.

Not reachable with an API token: since 1.4.1 a token request to this route answers 403 plugixa_exam_token_route. Call it as a signed-in WordPress user (from a script, with an Application Password) who holds the questions:edit permission.

Needs Plugixa Exam Pro, with the Passages app on in Plugixa Exam -> App Manager.

Note. The size limit is usually set by the server, not by Plugixa Exam: a recording must be under 200 MB and under the site’s PHP upload limit, which is often far lower. Read audio_limit_mb from Get Passage before you upload.

Request

POST https://your-site.example/wp-json/plugixa-exam/v1/passages/7/audio

Path parameters

Name	Type	Description
`id`	`integer`	The passage’s id

Request body

Content type: multipart/form-data

Field	Type	Required	Description
`file`	`file`	Yes	An MP3 (`.mp3`) or M4A (`.m4a`) recording, not empty, within the size limit.

The file is checked three ways: its extension, its real file type, and its audio content, which must read as MP3 or MP4 audio with a length. Renaming another file to .mp3 does not get it through. The previous recording is deleted only once the new one is safely stored, so a failed upload leaves the old one working. The recording is kept in a private folder and is never given a public URL.

Responses

`200` OK. `data` describes the recording now attached.

{
  "success": true,
  "data": {
    "has_audio": true,
    "audio_name": "lighthouse-keeper.mp3",
    "audio_seconds": 154
  }
}

Field	Type	Meaning
`data.has_audio`	`boolean`	`true` once the recording is stored
`data.audio_name`	`string`	The file name it was uploaded under, cleaned
`data.audio_seconds`	`integer`	Length of the recording, rounded up to the second

Errors

Status	Code	When
`404`	`plugixa_exam_not_found`	No passage with that id, or the passage is in the trash.
`400`	`plugixa_exam_audio_no_file`	No `file` part arrived in the request.
`413`	`plugixa_exam_audio_too_large`	The file is empty, over the size limit, or over the server’s PHP upload or request size.
`400`	`plugixa_exam_audio_wrong_kind`	The file is not a valid MP3 or M4A recording.
`422`	`plugixa_exam_audio_refused`	The site’s uploader refused the file.
`500`	`plugixa_exam_audio_refused`	The file could not be saved where it belongs.
`500`	`plugixa_exam_uploads_unavailable`	The site cannot accept uploads at the moment.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-exam/v1/passages/7/audio" \
  -u "$WP_USER:$WP_APP_PASSWORD" \
  -F "file=@lighthouse-keeper.mp3;type=audio/mpeg"

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-exam/v1/passages/7/audio');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Basic ' . base64_encode(getenv('WP_USER') . ':' . getenv('WP_APP_PASSWORD')),
    ],
    CURLOPT_POSTFIELDS     => [
        'file' => new CURLFile('lighthouse-keeper.mp3', 'audio/mpeg', 'lighthouse-keeper.mp3'),
    ],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', new Blob([await readFile('lighthouse-keeper.mp3')], { type: 'audio/mpeg' }), 'lighthouse-keeper.mp3');

const response = await fetch('https://your-site.example/wp-json/plugixa-exam/v1/passages/7/audio', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(`${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`),
  },
  body: form,
});
const { data } = await response.json();