NomonoPlatform docs

Reference

Sessions

A session groups the sources of one recording and gives each of them a role. Every job you create runs on a session.

Each microphone is one person's voice, mono or stereo, and a session can have one to four of them. A mixdown is a mono or stereo file with the voices already mixed, and it has to be the only source in its session. A session with microphones can also have one bed, which is the recording of an ambisonics array. The microphones and the bed must then be the same length, within 2.7 milliseconds. No source can be longer than 3600 seconds. Each source can be in only one session.

A bed must be the A-format recording straight from the array, and a 4-channel bed must be a WAV file without a channel mask, but the API checks neither. If a 4-channel bed is FLAC, or a WAV file with the quad channel mask 0x33 such as the Ambisonics B-format export from Nomono Cloud, every job on the session that makes a binaural mix or ADM files fails. To fix it, upload the bed again as WAV without a channel mask and create a new session with it. B-format and AmbiX beds aren't supported, and without the mask they're processed as if they were A-format.

We keep a session, its sources and its jobs' files until you delete the session or its retention runs out.

The session object

  • session_idstring

    The session's ID.

  • statusstring

    Always ready.

  • duration_snumber

    The length of the longest source, in seconds.

  • sourcesarray of objects

    The session's sources, in the order given.

  • alignmentstring

    Always sample_locked.

  • retention_daysnullable integer

    The retention_days sent when the session was created, while expires_at shows the retention that applies.

  • created_attimestamp

    When the session was created.

  • expires_atnullable timestamp

    When the session's retention runs out, after which we delete it with its files. It's null when no retention applies.

POST/v1/sessions

Create a session

Creates a session from your sources and their roles. If the session breaks one of the rules above, the request returns 422 session_invalid with the rule in message, and with the source in details.source_id when the rule concerns one source. The one exception is a source longer than 3600 seconds, which returns 400 validation_error.

Needs the jobs:write scope.

Body

  • sourcesarray of objectsrequired

    The recording's sources and their roles, in the order the outputs and analysis will use.

  • alignmentstring

    How the sources line up in time. The only accepted value is sample_locked.

    Defaults to sample_locked

  • retention_daysnullable integer

    Days to keep the session and its files. It defaults to your organization's retention if we've set one, and without either the session is kept until you delete it.

    1 to 3650

Returns

The session object.

curl -X POST "https://platform-api.nomono.co/v1/sessions" \  -H "Authorization: Bearer $NOMONO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "sources": [      {        "source_id": "src_01a1446f235c7448abbe096c9b9adf6c",        "role": "microphone",        "label": "Host"      },      {        "source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90",        "role": "microphone",        "label": "Guest"      },      {        "source_id": "src_01a144701c287e45b8d39f0a0f1e2d3c",        "role": "bed",        "array": "sennheiser-ambeo"      }    ],    "retention_days": 30  }'
201 Created
{  "session_id": "ses_01a14471a03b7c56a1e28d9f4b6c7d8e",  "status": "ready",  "duration_s": 1834.21,  "sources": [    {      "source_id": "src_01a1446f235c7448abbe096c9b9adf6c",      "role": "microphone",      "label": "Host",      "array": null,      "source": {        "source_id": "src_01a1446f235c7448abbe096c9b9adf6c",        "upload_id": "upl_01a1446f235c7448abbe096bfd043ae3",        "filename": "host.wav",        "format": "wav",        "channels": 1,        "sample_rate": 48000,        "duration_s": 1834.21,        "size_bytes": 176084204,        "device": null,        "status": "ready",        "created_at": "2026-10-16T09:02:11.204518Z",        "expires_at": "2026-11-15T09:12:44.518377Z"      }    },    {      "source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90",      "role": "microphone",      "label": "Guest",      "array": null,      "source": {        "source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90",        "upload_id": "upl_01a1446f8e917b23a4c06d1e5f7a8b92",        "filename": "guest.wav",        "format": "wav",        "channels": 1,        "sample_rate": 48000,        "duration_s": 1834.21,        "size_bytes": 176084204,        "device": null,        "status": "ready",        "created_at": "2026-10-16T09:03:02.611730Z",        "expires_at": "2026-11-15T09:12:44.518377Z"      }    },    {      "source_id": "src_01a144701c287e45b8d39f0a0f1e2d3c",      "role": "bed",      "label": null,      "array": "sennheiser-ambeo",      "source": {        "source_id": "src_01a144701c287e45b8d39f0a0f1e2d3c",        "upload_id": "upl_01a144701c2a7e45b8d39f0a1b2c3d4e",        "filename": "ambeo.wav",        "format": "wav",        "channels": 4,        "sample_rate": 48000,        "duration_s": 1834.21,        "size_bytes": 1056505004,        "device": null,        "status": "ready",        "created_at": "2026-10-16T09:03:38.402115Z",        "expires_at": "2026-11-15T09:12:44.518377Z"      }    }  ],  "alignment": "sample_locked",  "retention_days": 30,  "created_at": "2026-10-16T09:12:44.518377Z",  "expires_at": "2026-11-15T09:12:44.518377Z"}

GET/v1/sessions

List sessions

Returns your organization's sessions, newest first, a page at a time.

Needs the jobs:write scope.

Query parameters

  • limitinteger

    How many sessions per page.

    1 to 200Defaults to 50

  • cursorstring

    The next_cursor from the previous page.

Returns

  • sessionsarray of objects

    One page of sessions.

  • next_cursornullable string

    The value to send as cursor to get the next page. It's null on the last page.

curl "https://platform-api.nomono.co/v1/sessions?limit=1" \  -H "Authorization: Bearer $NOMONO_API_KEY"
200 OK
{  "sessions": [    {      "session_id": "ses_01a14471a03b7c56a1e28d9f4b6c7d8e",      "status": "ready",      "duration_s": 1834.21,      "sources": [        {          "source_id": "src_01a1446f235c7448abbe096c9b9adf6c",          "role": "microphone",          "label": "Host",          "array": null,          "source": {            "source_id": "src_01a1446f235c7448abbe096c9b9adf6c",            "upload_id": "upl_01a1446f235c7448abbe096bfd043ae3",            "filename": "host.wav",            "format": "wav",            "channels": 1,            "sample_rate": 48000,            "duration_s": 1834.21,            "size_bytes": 176084204,            "device": null,            "status": "ready",            "created_at": "2026-10-16T09:02:11.204518Z",            "expires_at": "2026-11-15T09:12:44.518377Z"          }        },        {          "source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90",          "role": "microphone",          "label": "Guest",          "array": null,          "source": {            "source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90",            "upload_id": "upl_01a1446f8e917b23a4c06d1e5f7a8b92",            "filename": "guest.wav",            "format": "wav",            "channels": 1,            "sample_rate": 48000,            "duration_s": 1834.21,            "size_bytes": 176084204,            "device": null,            "status": "ready",            "created_at": "2026-10-16T09:03:02.611730Z",            "expires_at": "2026-11-15T09:12:44.518377Z"          }        },        {          "source_id": "src_01a144701c287e45b8d39f0a0f1e2d3c",          "role": "bed",          "label": null,          "array": "sennheiser-ambeo",          "source": {            "source_id": "src_01a144701c287e45b8d39f0a0f1e2d3c",            "upload_id": "upl_01a144701c2a7e45b8d39f0a1b2c3d4e",            "filename": "ambeo.wav",            "format": "wav",            "channels": 4,            "sample_rate": 48000,            "duration_s": 1834.21,            "size_bytes": 1056505004,            "device": null,            "status": "ready",            "created_at": "2026-10-16T09:03:38.402115Z",            "expires_at": "2026-11-15T09:12:44.518377Z"          }        }      ],      "alignment": "sample_locked",      "retention_days": 30,      "created_at": "2026-10-16T09:12:44.518377Z",      "expires_at": "2026-11-15T09:12:44.518377Z"    }  ],  "next_cursor": "ses_01a14471a03b7c56a1e28d9f4b6c7d8e"}

GET/v1/sessions/{session_id}

Retrieve a session

Returns a session.

Needs the jobs:write scope.

Path parameters

  • session_idstringrequired

    The ID of the session.

Returns

The session object.

curl "https://platform-api.nomono.co/v1/sessions/ses_01a14471a03b7c56a1e28d9f4b6c7d8e" \  -H "Authorization: Bearer $NOMONO_API_KEY"
200 OK
{  "session_id": "ses_01a14471a03b7c56a1e28d9f4b6c7d8e",  "status": "ready",  "duration_s": 1834.21,  "sources": [    {      "source_id": "src_01a1446f235c7448abbe096c9b9adf6c",      "role": "microphone",      "label": "Host",      "array": null,      "source": {        "source_id": "src_01a1446f235c7448abbe096c9b9adf6c",        "upload_id": "upl_01a1446f235c7448abbe096bfd043ae3",        "filename": "host.wav",        "format": "wav",        "channels": 1,        "sample_rate": 48000,        "duration_s": 1834.21,        "size_bytes": 176084204,        "device": null,        "status": "ready",        "created_at": "2026-10-16T09:02:11.204518Z",        "expires_at": "2026-11-15T09:12:44.518377Z"      }    },    {      "source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90",      "role": "microphone",      "label": "Guest",      "array": null,      "source": {        "source_id": "src_01a1446f8e8f7b23a4c06d1c3e5f7a90",        "upload_id": "upl_01a1446f8e917b23a4c06d1e5f7a8b92",        "filename": "guest.wav",        "format": "wav",        "channels": 1,        "sample_rate": 48000,        "duration_s": 1834.21,        "size_bytes": 176084204,        "device": null,        "status": "ready",        "created_at": "2026-10-16T09:03:02.611730Z",        "expires_at": "2026-11-15T09:12:44.518377Z"      }    },    {      "source_id": "src_01a144701c287e45b8d39f0a0f1e2d3c",      "role": "bed",      "label": null,      "array": "sennheiser-ambeo",      "source": {        "source_id": "src_01a144701c287e45b8d39f0a0f1e2d3c",        "upload_id": "upl_01a144701c2a7e45b8d39f0a1b2c3d4e",        "filename": "ambeo.wav",        "format": "wav",        "channels": 4,        "sample_rate": 48000,        "duration_s": 1834.21,        "size_bytes": 1056505004,        "device": null,        "status": "ready",        "created_at": "2026-10-16T09:03:38.402115Z",        "expires_at": "2026-11-15T09:12:44.518377Z"      }    }  ],  "alignment": "sample_locked",  "retention_days": 30,  "created_at": "2026-10-16T09:12:44.518377Z",  "expires_at": "2026-11-15T09:12:44.518377Z"}

DELETE/v1/sessions/{session_id}

Delete a session

Deletes a session together with its sources, its jobs and their files, although the jobs still count in your usage. Any queued job whose processing hasn't started is cancelled. If one of the session's jobs is being processed, or can still finish after a timeout as the Jobs guide describes, the request returns 409 conflict with that job in details.job_id.

Needs the jobs:write scope.

Path parameters

  • session_idstringrequired

    The ID of the session.

Returns

An empty body, with the status 204 No Content.

curl -X DELETE "https://platform-api.nomono.co/v1/sessions/ses_01a14470f61c7a3e8b2d4c6f1e0a9b87" \  -H "Authorization: Bearer $NOMONO_API_KEY"
204 No Content