Tells you that the service is up, whether its database answers, which API version it runs, which optional features are switched on, and the website's addresses. Use it to test your connection before anything else - it needs no key.
Parameters: none. Send the request exactly as in the example.
What you get back: 200 OK with: status (ok, or degraded while the database does not answer); database (ok or down: whether our database answered a short query - asked at most every 10 seconds); api_version (1.0); site_build (the website's version); time (the server's clock, UTC); min_client_versions (per app id the lowest version still accepted - an older app gets ClientVersionUnsupported; empty: none is refused); features (true or false per optional feature: app_logins and browser_login - signing in from an app, signed_result_links - POST /jobs/{job_id}/result-links, webhooks, signup - POST /auth/signup, email_code_login - POST /auth/login/code, web_links - POST /auth/web-links); limits.picture (the largest picture we take: max_long_side and max_short_side in pixels, either way round - check a file against it before you upload; see Billing); pricing (our list prices: tiers from small to large, each with name, max_long_side, max_short_side and eur_per_min, and output_4k_eur_per_min, the price per minute of a job that delivers 4K); links (website pages an app shows before anyone signs in: the website; signup and pricing, both the start page, whose Sign Up opens the sign-up form - a signed-in account sees its own prices in GET /me; terms; privacy; support - the Contact Us part of the About Us page; this page).
Good to know: The answer can be up to 60 seconds old (Cache-Control: public, max-age=60); while the database does not answer it is not kept (no-store). It is 200 OK in both cases - check database. No Recuro-Client header is needed.
Downloads the description of this API in the OpenAPI 3.1 format: every endpoint, its parameters, its responses and every error code. Load it into an API tool (for example Postman or Insomnia) or a code generator to get a ready-made client.
Parameters: none. Send the request exactly as in the example.
What you get back: 200 OK with the YAML text (application/yaml). It can be up to 300 seconds old.
Good to know: The error codes are listed under x-error-codes at the end of the file, each with its HTTP status and whether a retry can help.
These endpoints are for apps in which a person signs in with an e-mail address and password (our plugins). If you connect your own server with an API key and secret, you need only POST /auth/token (optional) - go on to Account.
Gives you a new access token. With an API key (grant_typeclient_credentials): exchange your key and secret for a token that works for 1 hour, so that your secret travels only once an hour - useful when you send thousands of chunks. In an app (grant_typerefresh_token): swap the refresh token for a new pair of tokens before or after the access token expires.
Parameters
Name
Where
Type
Required
What it is
Authorization
header
string
with client_credentials
HTTP Basic with your API key and secret (curl -u KEY:SECRET). Send no Authorization header with refresh_token.
grant_type
body (JSON)
string
yes
client_credentials (API key) or refresh_token (an app).
refresh_token
body (JSON)
string
with refresh_token
The app's current refresh token (rmr_ and 43 characters).
What you get back: 200 OK with a Tokens object. client_credentials gives no refresh token: when the token expires, exchange the key again. refresh_token gives a new access token and a new refresh token; store the new refresh token at once - the old access token stops working immediately.
Good to know: An old refresh token is accepted once more within 60 seconds (in case the response was lost on the network). Used later than that, it signs the app out (RefreshTokenReused), because someone else must have a copy. At most 30 refreshes per hour per sign-in.
Signs a person in from one of our apps with their e-mail address and password, with the same rules and limits as the website's sign-in.
Parameters
Name
Where
Type
Required
What it is
email
body (JSON)
string
yes
The account's e-mail address. Example: jane@example.com.
password
body (JSON)
string
yes
The account's password. Send it once; never store it in the app.
client_id
body (JSON)
string
yes
Which of our apps signs in: premiere-uxp, resolve, avid-helper, ofx. Other values are refused (ValidationFailed).
client_version
body (JSON)
string
no (send it)
The app's version, up to 20 characters. Shown under Connected Apps. Example: 1.0.0.
device_name
body (JSON)
string
no
The computer's name, up to 100 characters. Shown under Connected Apps. Example: STUDIO.
host_app
body (JSON)
string
no
The editing application, up to 60 characters. Example: Adobe Premiere Pro.
host_version
body (JSON)
string
no
Its version, up to 30 characters. Example: 26.5.
os
body (JSON)
string
no
The operating system, up to 60 characters. Example: Windows 11 24H2.
What you get back: A Tokens object (statussigned_in), or - when the account uses two-factor authentication - {"status": "2fa_required", "challenge": "...", "expires_in": 300}: send the 6-digit authenticator code with that challenge to POST /auth/login/2fa within 300 seconds.
Good to know: An unknown address, a wrong password and an account made with Google, Apple or Microsoft (it has no password) all get the same InvalidCredentials, so the response never tells whether an address is registered. Such accounts use the browser sign-in or set a password with POST /auth/password/forgot. An account whose e-mail address is not confirmed yet gets AccountNotValidated and we e-mail it a new code (details.signup: send it with the code to POST /auth/signup/verify).
Finishes a sign-in of an account with two-factor authentication: you send the 6-digit code of the person's authenticator app (for example Google Authenticator) together with the challenge of the sign-in.
Parameters
Name
Where
Type
Required
What it is
challenge
body (JSON)
string
yes
The challenge of the 2fa_required response. It works for 300 seconds.
"E-mail me a code instead": e-mails a 6-digit sign-in code to the address, so that the person can sign in without a password (also accounts made with Google, Apple or Microsoft). Then send the code to POST /auth/login/code/verify.
Parameters
Name
Where
Type
Required
What it is
email
body (JSON)
string
yes
The address to send the code to; up to 254 characters.
client_id
body (JSON)
string
no
Which of our apps signs in: premiere-uxp, resolve, avid-helper, ofx. Other values are refused (ValidationFailed).
client_version
body (JSON)
string
no
The app's version, up to 20 characters. Shown under Connected Apps. Example: 1.0.0.
device_name
body (JSON)
string
no
The computer's name, up to 100 characters. Shown under Connected Apps. Example: STUDIO.
host_app
body (JSON)
string
no
The editing application, up to 60 characters. Example: Adobe Premiere Pro.
host_version
body (JSON)
string
no
Its version, up to 30 characters. Example: 26.5.
os
body (JSON)
string
no
The operating system, up to 60 characters. Example: Windows 11 24H2.
What you get back: 202 Accepted with statuscode_sent_if_registered, a sentence to show (detail) and expires_in (900 seconds: the code works for 15 minutes, once).
Good to know: The response is the same, and takes about the same time, whether or not the address has an account - so it never tells whether an address is registered. The e-mail holds the code only, no link; the app's name (from client_id) is put in it. Limits: 3 codes per address in 15 minutes and 10 a day; 10 and 50 per client address (RateLimited). Available when GET /health says features.email_code_login true.
{ "status": "code_sent_if_registered", "detail": "If jane@example.com has an account, we have e-mailed it a 6-digit code. It works for 15 minutes.", "expires_in": 900 }
Signs the person in with the e-mailed sign-in code. A right code also confirms the e-mail address.
Parameters
Name
Where
Type
Required
What it is
email
body (JSON)
string
yes
The address the code was sent to.
code
body (JSON)
string
yes
The 6 digits of the e-mail, as a string.
client_id
body (JSON)
string
yes
Which of our apps signs in: premiere-uxp, resolve, avid-helper, ofx. Other values are refused (ValidationFailed).
client_version
body (JSON)
string
no (send it)
The app's version, up to 20 characters. Shown under Connected Apps. Example: 1.0.0.
device_name
body (JSON)
string
no
The computer's name, up to 100 characters. Shown under Connected Apps. Example: STUDIO.
host_app
body (JSON)
string
no
The editing application, up to 60 characters. Example: Adobe Premiere Pro.
host_version
body (JSON)
string
no
Its version, up to 30 characters. Example: 26.5.
os
body (JSON)
string
no
The operating system, up to 60 characters. Example: Windows 11 24H2.
What you get back: A Tokens object (statussigned_in), or - when the account uses two-factor authentication - {"status": "2fa_required", "challenge": "...", "expires_in": 300}: send the 6-digit authenticator code with that challenge to POST /auth/login/2fa within 300 seconds.
Good to know: A wrong code answers InvalidCode with details.tries_left. The fifth wrong code ends the code (details.expired true), and so does its time (15 minutes): ask for a new one. A deactivated account gets AccountDeactivated.
Creates a new company account from one of our apps, with the website's rules. We e-mail a 6-digit code; the app sends it to POST /auth/signup/verify to finish. The new account starts on the Trial.
Parameters
Name
Where
Type
Required
What it is
first_name
body (JSON)
string
yes
Up to 30 characters.
last_name
body (JSON)
string
yes
Up to 30 characters.
company
body (JSON)
string
yes
The company's name, up to 100 characters.
email
body (JSON)
string
yes
A company address. On the production site, addresses of free and disposable e-mail providers are refused.
password
body (JSON)
string
yes
At least 10 characters.
country
body (JSON)
string
yes
The two-letter country code (ISO 3166-1 alpha-2). Example: SE. Accounts cannot be opened in the countries under sanctions - KP, CU, IR, SY: they answer SignupInvalid with the field code CountryNotServed.
state
body (JSON)
string
in the USA
The two-letter US state code when country is US.
accept_terms
body (JSON)
boolean
yes
Must be true: the person accepts the terms of service.
client_id
body (JSON)
string
yes
Which of our apps signs in: premiere-uxp, resolve, avid-helper, ofx. Other values are refused (ValidationFailed).
client_version
body (JSON)
string
no (send it)
The app's version, up to 20 characters. Shown under Connected Apps. Example: 1.0.0.
device_name
body (JSON)
string
no
The computer's name, up to 100 characters. Shown under Connected Apps. Example: STUDIO.
host_app
body (JSON)
string
no
The editing application, up to 60 characters. Example: Adobe Premiere Pro.
host_version
body (JSON)
string
no
Its version, up to 30 characters. Example: 26.5.
os
body (JSON)
string
no
The operating system, up to 60 characters. Example: Windows 11 24H2.
What you get back: 201 Created with statusverify_email, the signup id for the next step and expires_in (3600 seconds: the code works for 60 minutes).
Good to know: An address that has an account already gets the same response - its owner gets an e-mail instead - so the response never tells whether an address is registered. Form errors come as SignupInvalid with one entry per field in details.errors.
Finishes a sign-up (or the sign-in of an account whose address was not confirmed yet) with the e-mailed code: the account is confirmed and the app is signed in.
Parameters
Name
Where
Type
Required
What it is
signup
body (JSON)
string
yes
The signup id of POST /auth/signup (or details.signup of AccountNotValidated).
code
body (JSON)
string
yes
The 6 digits of the e-mail, as a string.
client_id
body (JSON)
string
yes
Which of our apps signs in: premiere-uxp, resolve, avid-helper, ofx. Other values are refused (ValidationFailed).
client_version
body (JSON)
string
no (send it)
The app's version, up to 20 characters. Shown under Connected Apps. Example: 1.0.0.
device_name
body (JSON)
string
no
The computer's name, up to 100 characters. Shown under Connected Apps. Example: STUDIO.
host_app
body (JSON)
string
no
The editing application, up to 60 characters. Example: Adobe Premiere Pro.
host_version
body (JSON)
string
no
Its version, up to 30 characters. Example: 26.5.
os
body (JSON)
string
no
The operating system, up to 60 characters. Example: Windows 11 24H2.
What you get back: A Tokens object (statussigned_in), or - when the account uses two-factor authentication - {"status": "2fa_required", "challenge": "...", "expires_in": 300}: send the 6-digit authenticator code with that challenge to POST /auth/login/2fa within 300 seconds.
Sends a new code for a sign-up whose e-mail did not arrive.
Parameters
Name
Where
Type
Required
What it is
signup
body (JSON)
string
yes
The signup id.
What you get back: 202 Accepted with the same fields as POST /auth/signup. The response comes after about 2.5 seconds, whether or not anything was sent.
Good to know: At most 3 new codes per sign-up, at least one minute apart. New codes have their own limits (3 per address in 15 minutes and 6 a day; 10 and 30 per client address), separate from the sign-up's first e-mail, so all 3 can be sent.
E-mails a 6-digit code for a new password, when the address has an account. Then send the code with the new password to POST /auth/password/reset.
Parameters
Name
Where
Type
Required
What it is
email
body (JSON)
string
yes
The account's e-mail address.
What you get back: 202 Accepted with statuscode_sent_if_registered and a sentence to show. The response is the same whether or not the address has an account. The code works for 15 minutes.
Sets a new password with the e-mailed code. Every other app of the account is signed out (as a reset on the website does) and this app is signed in.
Parameters
Name
Where
Type
Required
What it is
email
body (JSON)
string
yes
The account's e-mail address.
code
body (JSON)
string
yes
The 6 digits of the e-mail, as a string.
new_password
body (JSON)
string
yes
At least 10 characters.
client_id
body (JSON)
string
yes
Which of our apps signs in: premiere-uxp, resolve, avid-helper, ofx. Other values are refused (ValidationFailed).
client_version
body (JSON)
string
no (send it)
The app's version, up to 20 characters. Shown under Connected Apps. Example: 1.0.0.
device_name
body (JSON)
string
no
The computer's name, up to 100 characters. Shown under Connected Apps. Example: STUDIO.
host_app
body (JSON)
string
no
The editing application, up to 60 characters. Example: Adobe Premiere Pro.
host_version
body (JSON)
string
no
Its version, up to 30 characters. Example: 26.5.
os
body (JSON)
string
no
The operating system, up to 60 characters. Example: Windows 11 24H2.
What you get back: A Tokens object (statussigned_in), or - when the account uses two-factor authentication - {"status": "2fa_required", "challenge": "...", "expires_in": 300}: send the 6-digit authenticator code with that challenge to POST /auth/login/2fa within 300 seconds. A reset does not skip the second factor.
Request
curl -sS "$API/auth/password/reset" -H "Content-Type: application/json" \
-d '{"email": "jane@example.com", "code": "771204", "new_password": "a new long pass phrase", "client_id": "premiere-uxp", "client_version": "1.0.0"}'
Starts a browser sign-in, for accounts made with Google, Apple or Microsoft (they have no password). The person approves the app on our website in their normal browser; the app waits and then collects the tokens.
Parameters
Name
Where
Type
Required
What it is
client_id
body (JSON)
string
yes
Which of our apps signs in: premiere-uxp, resolve, avid-helper, ofx. Other values are refused (ValidationFailed).
client_version
body (JSON)
string
no (send it)
The app's version, up to 20 characters. Shown under Connected Apps. Example: 1.0.0.
device_name
body (JSON)
string
no
The computer's name, up to 100 characters. Shown under Connected Apps. Example: STUDIO.
host_app
body (JSON)
string
no
The editing application, up to 60 characters. Example: Adobe Premiere Pro.
host_version
body (JSON)
string
no
Its version, up to 30 characters. Example: 26.5.
os
body (JSON)
string
no
The operating system, up to 60 characters. Example: Windows 11 24H2.
code_challenge
body (JSON)
string
yes
The PKCE challenge: the SHA-256 of your verifier, base64url without padding - exactly 43 characters (see the example under Browser sign-in).
code_challenge_method
body (JSON)
string
yes
Only S256.
What you get back: 201 Created with: login_id (for the next two endpoints); user_code (show it in the app); verification_uri and verification_uri_complete (open the complete one in the system browser); expires_in (900 seconds: the request ends after 15 minutes); interval (seconds to wait between two polls of the token, 5).
Good to know: At most 10 browser sign-ins started per client address in 10 minutes.
Credential: none - the PKCE verifier in the body proves who you are
Asks whether the person has approved the browser sign-in yet, and collects the tokens once they have. Poll it every interval seconds.
Parameters
Name
Where
Type
Required
What it is
login_id
path
string
yes
The login_id of POST /auth/app-logins.
code_verifier
body (JSON)
string
yes
The PKCE verifier the app made (it never leaves the app before this request).
What you get back: 202 Accepted with {"status": "pending", "interval": 5, "expires_in": ...} while the person has not decided; 200 OK with a Tokens object after Allow - exactly once. Deny: AppLoginDenied.
Good to know: Polling faster than interval answers SlowDown with a longer interval in details.interval: use it from then on. At most 60 polls per minute per client address.
Credential: an access token (Bearer) · scope account:read
Opens a page of our website signed in, from an app the person is signed in to - the app's Top up..., Order history..., Account..., Open the Website, Connected Apps and Contact Support buttons, without a second sign-in. The answer is a one-time link: open it in the system browser at once. See Website pages from an app.
Parameters
Name
Where
Type
Required
What it is
Authorization
header
string
yes
Bearer and the access token of an app sign-in.
page
body (JSON)
string
yes
Which page: top_up (Top Up on a Prepaid plan; the upgrade dialog on the Trial; a short note on the other plans), orders (Order History), workspace, account (Account Settings), connected_apps (Connected Apps) or support (the Contact Us dialog).
What you get back: 201 Created with url (open it in the system browser), page, expires_in (60 seconds) and expires_at.
Good to know: Only for app sign-ins: an API key, or a token made from one, gets InsufficientScope (details.requiredapp_login). A link works once, for 60 seconds, and only while this sign-in is live. At most 5 links a minute per sign-in. Whether to offer it: features.web_links of GET /health and account.web_links of GET /me.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope account:read
Tells you who you are signed in as and what your account can do: the user, the company and its plan, the balance or the seconds left, your prices, your limits and links to the website pages for what the API does not do (paying, account settings). Use it as your first request: if it works, your key and secret are right.
Parameters
Name
Where
Type
Required
What it is
If-None-Match
header
string
no
The ETag of your last GET /me: when nothing has changed you get 304 Not Modified without a body - free: a 304 never counts against your limits. See Polling and ETags.
What you get back: 200 OK with a Me object and an ETag header.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope catalogue:read
Lists everything a job can be made of: the filters, the filters of which you can choose only one, the output formats and sizes, the output options and the presets (ready-made filter sets - ours and the ones you saved in the workspace). Read it once when your program starts and use its keys in settings.
Parameters
Name
Where
Type
Required
What it is
If-None-Match
header
string
no
The ETag of your last GET /catalogue (a free 304 when nothing has changed).
What you get back: 200 OK with a Catalogue object and an ETag header. The example above is shortened: the real response lists all 23 filters, 6 output formats and every preset you can use.
Credential: API key and secret (HTTP Basic) or an access token (Bearer) · scope catalogue:read
Tells you what a job would cost and whether it would start, without starting it. It runs exactly the checks the start runs. Ask it for a media you have uploaded (media_id), or for a file you have not uploaded yet (planned: its length and frame size).
Parameters
Name
Where
Type
Required
What it is
media_id
body (JSON)
string
this or planned
A ready media of yours. Example: med_4821.
planned
body (JSON)
object
this or media_id
A file you have not uploaded yet.
planned.duration_seconds
body (JSON)
number
with planned
Its length in seconds: more than 0, at most 86400 (24 hours). Example: 42.0.
planned.width
body (JSON)
integer
no
Its frame width in pixels, 0 to 16384. 0 (and height 0) for a sound-only file. Default: 0. For a video give both: left out, the file is quoted as sound only (tier sd) - a 2K film would be quoted at the HD price.
planned.height
body (JSON)
integer
no
Its frame height in pixels, 0 to 16384. Give both or neither. Default: 0. A picture larger than 2048 × 1556 (either way round) answers PictureTooLarge: it could not be uploaded.
planned.frame_rate
body (JSON)
object
no
Its frame rate as the file has it: whole numbers num and den, for example {"num": 24000, "den": 1001} for 23.976 fps or {"num": 25, "den": 1}; at most 1000 fps. Given, an MXF output at a frame rate MXF cannot hold (for example 16 or 18 fps) is refused at the quote. Left out, that check waits for the start.
settings
body (JSON)
object
yes
What the job does: either preset_id or filters (not both), optionally output_format and output_scaling.
settings.preset_id
body (JSON)
string
one of the two
A preset of GET /catalogue (presets[].id): its filters, output format and output scaling. Example: pre_90. A preset's upload server (a website setting) is never used by an API job: the result stays here for you to download.
settings.filters
body (JSON)
array of strings
one of the two
Filter keys of GET /catalogue (filters[].key; the full list is in Filters). At most one of light_dust_and_scratches, medium_dust_and_scratches and heavy_dust_and_scratches. An empty list [] runs no filter: the job only re-encodes the media into the output format (and scales it, with output_scaling), at the full price of its tier. Example: ["noise", "medium_dust_and_scratches"].
settings.output_format
body (JSON)
string
no
The result's file type: mov_prores_422_hq, mov_prores_4444, mxf_dnxhr_hqx, mxf_dnxhr_444, mp4_h264 or mp4_hevc. Default: the preset's format, or mov_prores_422_hq with filters.
settings.output_scaling
body (JSON)
string
no
The result's height: source (the same as the media), 1080 (HD) or 2160 (4K). Default: the preset's scaling, or source with filters. A larger output can raise the price (see Billing).
output
body (JSON)
object
no
As for POST /jobs (a value it refuses answers ValidationFailed here too); only output.format and output.scaling change the price. Send the same options you will start the job with: combinations the start refuses are refused here.
What you get back: 200 OK with a Quote object. covers false means the job would be refused now; refusal then holds the error code, sentence and details the start would give (for example BalanceInsufficient). A quote is not stored and reserves nothing.
Good to know: The quote runs the start's own checks, in the start's order: first the media, the output container and the output options - the combinations POST /jobs refuses with OptionConflict (an MXF output at a frame rate MXF cannot hold or smaller than 256×120 pixels, MXF or output.audionone for a sound-only file, a sound-only media whose sound is silent, match_source with an output scaling or with a stretched or squeezed picture, output.frame_ratesource with natural speed or high frame rate) and FrameRateChangedAtIngest - then the balance or quota and the trial's clip length. Each answers covers false with that refusal, so your program can show it before anything is exported or uploaded. A planned file has not been analysed yet: its checks use what you send (the frame size, sound only, planned.frame_rate); the crop, silent sound, a stretched picture and a removed pulldown are known only after the analysis, so those checks wait for the start.
You opened a sign-in link from your e-mail. Signing in here signs you in on this device (this browser). If you asked for the link in another window, you can type its code there instead.
