API

This page is of interest to developers of Project-W, but also to people who want to write custom clients for it (like bash or python scripts or anything else). If the latter is the case then focus on the client-facing routes and ignore the runner-facing ones.

Note

If you want to develop a client that is intended to replace the current frontend (not just as an addition) then make sure that is has an /local/activate and an /auth/local/reset-password route! The backend expects that the client has these since it puts them into the emails it sends to the users and forwards. They should accept a token as a query string that contains the activation/password reset token.

General

The REST API of the backend is divided into these sections:

/api/jobs/*
/api/users/*
/api/local-account/*
/api/oidc/*
/api/ldap/*
/api/runners/*
/api/admins/*

The section 1 to 5 as well as info routes that are in none of these sections should be of interest to you if you want to write your own client. We will call them client-facing routes from now on. The sixth section should be used by runners only (runner-facing), and the seventh is only for administration purposes.

Some of these routes are protected by an auth token. This token can either be provided through a cookie called token or as an http bearer token. Use the method that is more convenient for your application. You can generate an auth token from the official frontend under the Security tab.

We made the following design decision regarding when to use GET, POST or PUT routes:

GET: Requests are both safe and idempotent
PUT: Requests are not safe but idempotent
POST: Requests are neither safe nor idempotent
DELETE: Like POST but it will always result in a deletion of a resource (while POSTs generally result in a creation of a new resource)

A safe operation is one that doesn’t cause a write to the database (only read). An idempotent request is one that returns the same data regardless of how often you request it (e.g. the returned data of the 10th request will be the same as the one of the 1st).

We make use of Pydantic to validate all input and output models of our API. These models are also part of the OpenAPI documentation so that you can use the to craft HTTP requests more easily.

If a route is not successful (http status code not in the 200 range) and the error was created by the backend code (and not the application framework, proxies in between, …) it will return an ErrorResponse object which contains a detail with more information about the error (e.g. an error message or a list of inputs that didn’t pass type validation)

OpenAPI docs

We would recommend to visit the OpenAPI docs UI (formerly known as Swagger UI) under /docs of a hosted Project-W instance. Alternatively if you prefer every Project-W instance also comes with a Redoc UI under /redoc. The API reference below should only be considered as a quick overview, the OpenAPI and Redoc UIs are far superior to this documentation.

Quick overview

general
GET /api/about
About

Returns a brief description of Project-W, a link to the GitHub repository containing the backend’s code, the backend’s version currently running on the system as well as the imprint of this instance (if it was configured by the instance’s admin).

Example request:
GET /api/about HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "description": "string",
    "source_code": "string",
    "version": "string",
    "git_hash": "string",
    "imprint": {
        "name": "string",
        "email": "string",
        "url": "https://example.com",
        "additional_imprint_html": "string"
    },
    "terms_of_services": {},
    "job_retention_in_days": 1,
    "site_banners": [
        {
            "id": 1,
            "html": "string",
            "urgency": 1
        }
    ]
}
GET /api/auth_settings
Auth Settings

Returns all information required by the client regarding which account types and identity providers this instance supports, whether account signup of local accounts is allowed, whether the creation of API tokens is allowed for each account type and so on.

Example request:
GET /api/auth_settings HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "local_account": {
        "mode": "disabled",
        "allowed_email_domains": [
            "string"
        ],
        "allow_creation_of_api_tokens": true
    },
    "oidc_providers": {},
    "ldap_providers": {}
}
users
DELETE /api/users/invalidate_token
Invalidate Token

Invalidate the local token with the provided id. Doesn’t work for OIDC tokens. After calling this route the token with the provided id can’t be used anymore.
Query Parameters:

token_id (integer) – (Required)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
DELETE /api/users/invalidate_all_tokens
Invalidate All Tokens

Invalidate all local tokens of the logged in user account. Doesn’t work for OIDC tokens. After calling this route all local tokens of the logged in user account won’t work anymore.
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
DELETE /api/users/logout
Logout

Like /invalidate_token, but invalidates the token currently being used and additionally unsets the token cookie
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
POST /api/users/get_new_api_token
Get New Api Token

Create a new API token. The main difference between API tokens and regular auth tokens is that API tokens never expire. Only create them if necessary and only use a different token for each device/service so that it is easy to invalidate one of them if a device gets compromised. The provided name has the purpose of being able to identify which token belongs to which device/service.THe successfully response contains the newly created token.
Query Parameters:

name (string) – (Required)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
Creation of api tokens is disabled for your identity provider

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/users/get_all_token_info
Get All Token Info

Get a list of all token id’s and names currently in use by this account, sorted by last usage timestamp.

Example request:
GET /api/users/get_all_token_info HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "name": "string",
        "admin_privileges": true,
        "explicit": true,
        "expires_at": "2026-03-02T15:34:52.531820",
        "last_usage": "2026-03-02T15:34:52.531820"
    }
]
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/users/info
Info

This route returns all information about the currently logged in user.

Example request:
GET /api/users/info HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "email": "string",
    "accepted_tos": {},
    "provider_name": "string",
    "user_type": "local",
    "is_verified": true
}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
POST /api/users/accept_tos
Accept Tos

By calling this route the user accepts to the terms of service specified by the submitted tos_id and tos_version. Only if a user has accepted the newest version of every term of service of this instance they are allowed to use this service.
Query Parameters:

tos_id (integer) – (Required)

tos_version (integer) – (Required)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
No term of service with that id or version exists

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
DELETE /api/users/delete
Delete

Deletes the currently logged in user and all information related to it (like jobs, tokens, etc.)
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
local-account
POST /api/local-account/login
Login

Log in to an existing local Project-W account. This is an OAuth2 compliant password request form where the username is the user’s email address. A successful response will contain a token that needs to be attached in the authentication header of responses for routes that require the user to be logged in. If logging in with an admin account the returned auth token will not give you admin privileges by default. If you need a token with admin privileges then specify the scope ‘admin’ during login.
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Authentication was unsuccessful

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Request Headers:

user-agent
POST /api/local-account/signup
Signup

Create a new local Project-W account. The provided email must be valid and the password must adhere to certain criteria (must contain at least one lowercase letter, uppercase letter, number, special character and at least 12 characters in total) and the email can’t already be in use by another account.

Example request:
POST /api/local-account/signup HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "email": "string",
    "password": "********"
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
400 Bad Request –
Email or password have invalid syntax

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
405 Method Not Allowed –
Signup of new accounts is disabled on this server

Example response:
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
POST /api/local-account/activate
Activate

Activate a local Project-W account, meaning validate it’s email address. The token was sent to the user on account creation, email address change or when they specifically requested an email with the resend_activation_email route. Only activated users are able to submit transcription jobs and actually use this service.
Query Parameters:

token (string) – (Required)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
400 Bad Request –
Activation token doesn’t match any LoginContext, or user has already been activated

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
401 Unauthorized –
Activation token invalid

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
GET /api/local-account/resend_activation_email
Resend Activation Email

This will resend an activation email to the user like the one the user got when their account was created. Useful if they forgot to click on the link and lost the old email. Can only be requested if the user is not verified yet.

Example request:
GET /api/local-account/resend_activation_email HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
400 Bad Request –
This user is not a local user or is already activated

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/local-account/request_password_reset
Request Password Reset

Requests a password reset email that will be sent to the user containing a link to a password reset page. The provided email address must belong to an existing local Project-W account.

Query Parameters:

email (string) – (Required)

Example request:
GET /api/local-account/request_password_reset?email=string HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
400 Bad Request –
Email invalid

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
POST /api/local-account/reset_password
Reset Password

Resets the password of an account to the provided password. The token is the one from the password reset email that can be requested with the /request_password_reset route.

Example request:
POST /api/local-account/reset_password HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "token": "********",
    "new_password": "********"
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
400 Bad Request –
Password reset token doesn’t match any user

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
401 Unauthorized –
Password reset token invalid

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
POST /api/local-account/change_user_email
Change User Email

Change the email address of a local Project-W account. This change will only take effect after the user has clicked on the link in the activation email that this route sends to the new email address.

Example request:
POST /api/local-account/change_user_email HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "new_email": "string",
    "password": "********"
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
400 Bad Request –
Email domain not allowed or email already in use

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
POST /api/local-account/change_user_password
Change User Password

Change the password of a local Project-W account. In contrary to requesting a password reset email this route is authenticated meaning that to use this route the user must still be able to log in into their account, but it changes the password immediately without going through a link in an email first.

Example request:
POST /api/local-account/change_user_password HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "new_password": "********",
    "password": "********"
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
oidc
GET /api/oidc/login/{idp_name}
Oidc-Redirect

Start an OIDC login flow. This route will redirect you to the login page of the identity provider ‘idp_name’. This name was specified by the admin in the config of this instance. Use the /api/auth_settings route to get the authentication-related configuration of this instance.

Parameters:

idp_name (string)

Example request:
GET /api/oidc/login/{idp_name} HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
GET /api/oidc/auth/{idp_name}
Oidc-Auth

Landing route: After authenticating on the login page of the identity provider the provider will redirect you to this route so that the backend can process the IdP’s response. This route will then redirect you to the official client’s page (as set by the instance’s admin) so that the client can get and store the OIDC id_token.

Parameters:

idp_name (string)

Example request:
GET /api/oidc/auth/{idp_name} HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{}
400 Bad Request –
Could not authorize IdP access token

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
401 Unauthorized –
Validation error of id_token

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Not enough information or missing scope

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Request Headers:

user-agent

Response Headers:

WWW-Authenticate
ldap
POST /api/ldap/login/{idp_name}
Login

Log in with an LDAP user queried from the LDAP server with the name ‘idp_name’. This name was specified by the admin in the config of this instance. Use the /api/auth_settings route to get the authentication-related configuration of this instance. If logging in with an admin account the returned auth token will not give you admin privileges by default. If you need a token with admin privileges then specify the scope ‘admin’ during login.
Parameters:

idp_name (string)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
400 Bad Request –
idp_name is invalid

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
401 Unauthorized –
Authentication was unsuccessful

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Request Headers:

user-agent
jobs
POST /api/jobs/submit_settings
Submit Settings

Submit a new job settings object to the backend. If is_new_default is set to True this set of job settings will become the new default for this account and if no job settings object is specified during job submission this set of settings will be used. If it is set to False then this set of settings will only be used if specified explicitly during job submission. Returns the id of the newly created job settings object which can then be used to reference these job settings during job submission.

Query Parameters:

is_new_default (boolean)

Example request:
POST /api/jobs/submit_settings HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "task": "transcribe",
    "model": "tiny",
    "language": "af",
    "alignment": {
        "processing": {
            "highlight_words": true,
            "max_line_count": 1,
            "max_line_width": 1
        },
        "return_char_alignments": true,
        "interpolate_method": "nearest"
    },
    "diarization": {
        "min_speakers": 1,
        "max_speakers": 1
    },
    "vad_settings": {
        "vad_onset": 1.0,
        "vad_offset": 1.0,
        "chunk_size": 1
    },
    "asr_settings": {
        "beam_size": 1,
        "patience": 1.0,
        "length_penalty": 1.0,
        "temperature": 1.0,
        "temperature_increment_on_fallback": 1.0,
        "compression_ratio_threshold": 1.0,
        "log_prob_threshold": 1.0,
        "no_speech_threshold": 1.0,
        "initial_prompt": "string",
        "suppress_tokens": [
            1
        ],
        "suppress_numerals": true
    },
    "email_notification": true
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

1
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/jobs/default_settings
Default Settings

Returns the default job settings of the current account. If no job settings id is explicitly specified during job submission then these job settings will be used for the job. These job settings where either set previously using the submit_settings route or are the application defaults.

Example request:
GET /api/jobs/default_settings HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "task": "transcribe",
    "model": "tiny",
    "language": "af",
    "alignment": {
        "processing": {
            "highlight_words": true,
            "max_line_count": 1,
            "max_line_width": 1
        },
        "return_char_alignments": true,
        "interpolate_method": "nearest"
    },
    "diarization": {
        "min_speakers": 1,
        "max_speakers": 1
    },
    "vad_settings": {
        "vad_onset": 1.0,
        "vad_offset": 1.0,
        "chunk_size": 1
    },
    "asr_settings": {
        "beam_size": 1,
        "patience": 1.0,
        "length_penalty": 1.0,
        "temperature": 1.0,
        "temperature_increment_on_fallback": 1.0,
        "compression_ratio_threshold": 1.0,
        "log_prob_threshold": 1.0,
        "no_speech_threshold": 1.0,
        "initial_prompt": "string",
        "suppress_tokens": [
            1
        ],
        "suppress_numerals": true
    },
    "email_notification": true
}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
POST /api/jobs/submit_job
Submit Job

Submit a new transcription job. If the job_settings_id is omitted the account defaults will be used. If you want to define the job settings then create a job settings object using the submit_settings route and then set job_settings_id here to the returned integer. Returns the id of the newly created job.
Query Parameters:

job_settings_id ({'integer', 'null'})

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

1
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
Not an audio file or provided job_settings_id was invalid

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
415 Unsupported Media Type –
The provided audio files has an invalid format

Example response:
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/jobs/count
Count

Returns the total amount of jobs this user has after applying the provided filter options. exclude_finished excludes finished jobs (both successful and aborted) while exclude_downloaded excludes finished jobs where the transcript was already downloaded at least ones.

Query Parameters:

exclude_finished (boolean) – (Required)

exclude_downloaded (boolean) – (Required)

Example request:
GET /api/jobs/count?exclude_finished=True&exclude_downloaded=True HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

1
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/jobs/get
Get

Returns a list of job ids sorted and filtered by the specified criteria. start_index and end_index specify which jobs to return from the sorted list, e.g. a start_index of 0 and end_index of 9 will return the first 10 jobs, while a start_index of 10 and and end_index of 19 will return the next 10 and so on.

Query Parameters:

start_index (integer) – (Required)

end_index (integer) – (Required)

sort_key (string) – (Required)

descending (boolean) – (Required)

exclude_finished (boolean) – (Required)

exclude_downloaded (boolean) – (Required)

Example request:
GET /api/jobs/get?start_index=1&end_index=1&sort_key=creation_time&descending=True&exclude_finished=True&exclude_downloaded=True HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

[
    1
]
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/jobs/info
Info

Returns a list of job objects containing all information related to each of the specified jobs. Note that job infos will be returned in no specific order, please use the get route to get an ordering of jobs by id and only use this route to get additional information about these jobs.

Query Parameters:

job_ids (array) – (Required)

Example request:
GET /api/jobs/info?job_ids=%5B1%5D HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "progress": 1.0,
        "abort": true,
        "creation_timestamp": "2026-03-02T15:34:52.531820",
        "file_name": "string",
        "finish_timestamp": "2026-03-02T15:34:52.531820",
        "runner_name": "string",
        "runner_id": 1,
        "runner_version": "string",
        "runner_git_hash": "string",
        "runner_source_code_url": "string",
        "downloaded": true,
        "error_msg": "string",
        "settings": {
            "task": "transcribe",
            "model": "tiny",
            "language": "af",
            "alignment": {
                "processing": {
                    "highlight_words": true,
                    "max_line_count": 1,
                    "max_line_width": 1
                },
                "return_char_alignments": true,
                "interpolate_method": "nearest"
            },
            "diarization": {
                "min_speakers": 1,
                "max_speakers": 1
            },
            "vad_settings": {
                "vad_onset": 1.0,
                "vad_offset": 1.0,
                "chunk_size": 1
            },
            "asr_settings": {
                "beam_size": 1,
                "patience": 1.0,
                "length_penalty": 1.0,
                "temperature": 1.0,
                "temperature_increment_on_fallback": 1.0,
                "compression_ratio_threshold": 1.0,
                "log_prob_threshold": 1.0,
                "no_speech_threshold": 1.0,
                "initial_prompt": "string",
                "suppress_tokens": [
                    1
                ],
                "suppress_numerals": true
            },
            "email_notification": true
        },
        "step": "not_queued"
    }
]
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
POST /api/jobs/abort
Abort

Aborts a currently running job. This will put the job into a failed state with an error message saying that the job was aborted. Any processing of this job will be canceled.

Example request:
POST /api/jobs/abort HTTP/1.1
Host: example.com
Content-Type: application/json

[
    1
]
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
At least one of jobs is not running

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
DELETE /api/jobs/delete
Delete

Deletes a completed (aborted/successfully finished) job. To delete a currently running job please use the abort route first and then delete it using this route.

Example request:
DELETE /api/jobs/delete HTTP/1.1
Host: example.com
Content-Type: application/json

[
    1
]
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
At least one of jobs is running

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/jobs/download_transcript
Download Transcript

Downloads the transcript of a successfully finished job. The transcript can be downloaded in multiple formats. Returns the transcript as a string.

Query Parameters:

job_id (integer) – (Required)

transcript_type (string) – (Required)

Example request:
GET /api/jobs/download_transcript?job_id=1&transcript_type=as_txt HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
No job with that id exists or that job isn’t finished

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
GET /api/jobs/events
Events

This is a special route for subscribing to server-sent events (SSE) which all contain an event field. Currently there are three events: job_created, job_updated and job_deleted. As data they all return the job id of the job the event refers to (i.e. the id of the job that just got created, updated or deleted). This route can be used to only fetch job info using the info route when it actually has changed without having to periodically re-fetch the job info of all jobs. Refer to https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#listening_for_custom_events for more information about SSE.

Example request:
GET /api/jobs/events HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
admins
POST /api/admins/create_runner
Create Runner

Create a new global runner that can be used by all users of this instance. Returns the id and the runner token of the newly created runner. Put this token into the config file of the runner that you are trying to host. Create a new runner token for each new runner that you want to host using this route!
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "token": "string"
}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
DELETE /api/admins/invalidate_runner
Invalidate Runner

Invalidate the token of a runner and delete it from the database and redis. If it has any jobs assigned at the time of invalidation these jobs will be reassigned to a different runner. Call this route immediately ones you find out that a runner token was compromised!
Query Parameters:

runner_id (integer) – (Required)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
POST /api/admins/add_site_banner
Add Site Banner

Add a new banner to the website that will be broadcasted to all users. Returns the id of the created banner. Banners with higher urgency will be displayed first. The text of a banner with an urgency between 100 and 200 (excluding) will be highlighted in red. Banners with an urgency of 200 and more will have a red background.

Example request:
POST /api/admins/add_site_banner HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "html": "string",
    "urgency": 1
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

1
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
DELETE /api/admins/delete_site_banner
Delete Site Banner
Query Parameters:

banner_id (integer) – (Required)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
POST /api/admins/send_email_to_all_users
Send Email To All Users

Sends out an email with the provided content to all users of this Project-W instance, regardless whether they are local accounts, oidc accounts or ldap accounts. The body is in plaintext format, don’t forget to include line breaks for longer emails.

Example request:
POST /api/admins/send_email_to_all_users HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "subject": "string",
    "body": "string"
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{}
401 Unauthorized –
Validation error of auth token, or not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
Token doesn’t grand enough permissions

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate

WWW-Authenticate
runners
POST /api/runners/register
Register

Registers the runner with the given runner_id as online. Starting from the registration, the runner must periodically send heartbeat requests to the manager, or it may be unregistered. Returns the runner id on success.

Example request:
POST /api/runners/register HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "version": "string",
    "git_hash": "string",
    "source_code_url": "string",
    "priority": 1
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "session_token": "string"
}
401 Unauthorized –
No runner with that token exists, nor not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
This runner is currently already registered as online

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate
POST /api/runners/unregister
Unregister

Unregisters an online runner. This will mark the runner as offline and no heartbeat or similar request will be possible anymore until another register request was performed.
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
No runner with that token exists, nor not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
Response Headers:

WWW-Authenticate
GET /api/runners/retrieve_job_info
Retrieve Job Info

The runner can retrieve metadata about the job that was assigned to it. This includes e.g. the job settings. The runner should call this route BEFORE it calls retrieve_job_audio to first make sure it can process the job. retrieve_job_info doesn’t mark the job as running yet, only retrieve_job_audio will do that.

Query Parameters:

session_token (string) – (Required)

Example request:
GET /api/runners/retrieve_job_info?session_token=string HTTP/1.1
Host: example.com
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "settings": {
        "task": "transcribe",
        "model": "tiny",
        "language": "af",
        "alignment": {
            "processing": {
                "highlight_words": true,
                "max_line_count": 1,
                "max_line_width": 1
            },
            "return_char_alignments": true,
            "interpolate_method": "nearest"
        },
        "diarization": {
            "min_speakers": 1,
            "max_speakers": 1
        },
        "vad_settings": {
            "vad_onset": 1.0,
            "vad_offset": 1.0,
            "chunk_size": 1
        },
        "asr_settings": {
            "beam_size": 1,
            "patience": 1.0,
            "length_penalty": 1.0,
            "temperature": 1.0,
            "temperature_increment_on_fallback": 1.0,
            "compression_ratio_threshold": 1.0,
            "log_prob_threshold": 1.0,
            "no_speech_threshold": 1.0,
            "initial_prompt": "string",
            "suppress_tokens": [
                1
            ],
            "suppress_numerals": true
        },
        "email_notification": true
    }
}
401 Unauthorized –
No runner with that token exists, nor not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
No job assigned or job not in database

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
405 Method Not Allowed –
The assigned job was aborted by the user

Example response:
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
This runner is currently not registered as online, or session_token is invalid

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate
POST /api/runners/retrieve_job_audio
Retrieve Job Audio

The runner streams the audio binary data of the job it got assigned over this route. Additionally this route will mark the job a currently being processed by this runner. Before calling this route the runner should have called retrieve_job_info first.
Query Parameters:

session_token (string) – (Required)

Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{}
401 Unauthorized –
No runner with that token exists, nor not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
No job assigned

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
405 Method Not Allowed –
The assigned job was aborted by the user

Example response:
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
This runner is currently not registered as online, or session_token is invalid

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate
POST /api/runners/submit_job_result
Submit Job Result

The runner submits the result of processing the job it got assigned over this route. The result can either be that the job failed (in which case the runner submits an error message) or that the job was successful (in which case the runner submits the transcript in all possible formats). This route will mark the job as failed or successful and notify the user over email if they activated email notifications for this job.

Query Parameters:

session_token (string) – (Required)

Example request:
POST /api/runners/submit_job_result?session_token=string HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "error_msg": "string",
    "transcript": {
        "as_txt": "string",
        "as_srt": "string",
        "as_tsv": "string",
        "as_vtt": "string",
        "as_json": {}
    }
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

string
401 Unauthorized –
No runner with that token exists, nor not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
400 Bad Request –
Runner not processing a job

Example response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
This runner is currently not registered as online, or session_token is invalid

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate
POST /api/runners/heartbeat
Heartbeat

The heartbeat route that the runner has to periodically call to not be unregistered automatically by the backend. Over the response of this route the runner will also be notified about a new job that it got assigned or an abort request for a job the runner is currently processing.

Query Parameters:

session_token (string) – (Required)

Example request:
POST /api/runners/heartbeat?session_token=string HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "progress": 1.0
}
Status Codes:
200 OK –
Successful Response

Example response:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "abort": true,
    "job_assigned": true
}
401 Unauthorized –
No runner with that token exists, nor not authenticated

Example response:
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "detail": "error message"
}
403 Forbidden –
This runner is currently not registered as online, or session_token is invalid

Example response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "detail": "error message"
}
422 Unprocessable Entity –
Validation Error

Example response:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "detail": [
        {
            "loc": [
                "string",
                1
            ],
            "msg": "string",
            "type": "string",
            "input": {},
            "ctx": {}
        }
    ]
}
Response Headers:

WWW-Authenticate