Upload API

Publish plugins on oplug1 from a script, a build step or an AI assistant. One HTTP request does what the upload page does, under the same rules.

This text is also available as plain Markdown at https://oplug1.dev/api.md, which is the address to give an AI assistant.

No script needed if the plugin is built in your GitHub repo: link it on the plugin's Manage page under "Automatic updates from GitHub", and new builds or releases are published here by themselves.

Quick start

Step 1. Sign in and make a token at https://oplug1.dev/settings/tokens/. The token is shown once.

Step 2. Put it in an environment variable, not in code: export OPLUG1_TOKEN=oplug1_...

Step 3. Check it works:

curl -H "Authorization: Bearer $OPLUG1_TOKEN" https://oplug1.dev/api/v1/me

Step 4. Publish a new plugin:

curl -X POST https://oplug1.dev/api/v1/plugins \
  -H "Authorization: Bearer $OPLUG1_TOKEN" \
  -F name="My Synth" \
  -F type=synth \
  -F summary="A warm two-oscillator synth engine." \
  -F files=@build/my-synth.op1p \
  -F rights=yes

Step 5. Later, publish a new release of it:

curl -X POST https://oplug1.dev/api/v1/plugins/my-synth/releases \
  -H "Authorization: Bearer $OPLUG1_TOKEN" \
  -F version=1.1 \
  -F changelog="Fixed the filter envelope." \
  -F files=@build/my-synth.op1p \
  -F rights=yes

Tokens

Every request carries the header Authorization: Bearer followed by a space and your token. Nothing else signs a request in: cookies are ignored.

A token can upload plugins and releases and read your own plugins. It cannot change your profile, edit or delete anything, or sign in to the site. Anyone who has your token can upload as you, so keep it out of public repositories, logs and chat messages. Revoke a token at https://oplug1.dev/settings/tokens/ and it stops working at once.

Addresses

Request What it does
GET /api/v1/me Your username, your plugins, the limits and how much of them is used.
GET /api/v1/plugins Your plugins.
POST /api/v1/plugins Publish a new plugin with its first release.
GET /api/v1/plugins/SLUG One of your plugins, with its releases and files.
POST /api/v1/plugins/SLUG/releases Publish a new release of a plugin you already have.
POST /api/v1/plugins/SLUG/files Add a file to a release that exists, such as a build for one more firmware.

SLUG is the plugin's link name: the last part of its address, https://oplug1.dev/your-username/SLUG/.

Uploads are sent as multipart/form-data, which is what curl's -F does. JSON bodies are not accepted. Every answer is JSON.

Publishing a new plugin

POST /api/v1/plugins

Field Needed Meaning
name yes The plugin's name, up to 60 characters.
type yes One of: synth, drum, effect, sequencer, other.
summary yes One line, up to 140 characters. Shown on browse pages.
files yes A plugin file ending in .knl, .op1p or .opmod, up to 2 MB. Repeat the field to send builds for several firmwares.
rights yes yes. It states that you wrote the plugin or have the right to distribute it, and that its licence allows it to be shared here.
slug no The link name: lowercase letters, digits and hyphens, up to 40 characters. Left out, it is made from the name. It cannot be changed later.
version no Any label, such as 1.0 or beta 3. Left out, it is 1.0.
changelog no Markdown. What is new.
description no Markdown. What the plugin does and how its controls behave.
tags no Up to 5, separated by commas, for example reverb, lo-fi.
license no Left out, it is GPL-3.0-or-later. One of: GPL-3.0-or-later, GPL-3.0-only, GPL-2.0-or-later, AGPL-3.0-or-later, LGPL-3.0-or-later, MIT, BSD-3-Clause, Apache-2.0, CC0-1.0, free-to-share, proprietary.
source_url no An https:// link to the source code.
docs_url no An https:// link to documentation.
ports_welcome no yes lets other members publish ports of this plugin to other firmwares, no does not. Left out, it follows your profile setting, which is yes unless you switched it off.
original_author no Only for your port of someone else's plugin that is not on this site: the name its author goes by. source_url is then needed.
original_url no An https:// link to that original.
screenshots no PNG, JPG or WebP, up to 5 MB each, at most 8. Repeat the field. The first is the cover.
audio no One MP3, OGG or M4A clip, up to 30 seconds and 2 MB.

Each plugin file is listed for the firmware its extension belongs to:

Firmware Extension Its name in field names
op1r .op1p op1r
hundekraft .knl hundekraft
Opus .opmod opus

To state which firmware versions a build supports, add versions_ plus the firmware's name (for example -F versions_op1r="2.0 and later"), and tested_ plus the firmware's name for the version you last tested on. Both are optional.

A fuller example, with the description read from a file (curl's < sends a file's text as the field's value):

curl -X POST https://oplug1.dev/api/v1/plugins \
  -H "Authorization: Bearer $OPLUG1_TOKEN" \
  -F name="My Synth" \
  -F slug=my-synth \
  -F type=synth \
  -F summary="A warm two-oscillator synth engine." \
  -F "description=<README.md" \
  -F tags="warm, analog" \
  -F source_url=https://github.com/you/my-synth \
  -F files=@build/my-synth.op1p \
  -F files=@build/my-synth.knl \
  -F [email protected] \
  -F [email protected] \
  -F rights=yes

The answer has status 201:

{"ok": true,
 "message": "Published at https://oplug1.dev/you/my-synth/",
 "plugin": {"slug": "my-synth", "name": "My Synth", "type": "synth", "status": "published",
            "url": "https://oplug1.dev/you/my-synth/", "latest_version": "1.0", "releases": [ ... ]}}

A status of pending means the upload was taken and will appear once an administrator approves it. Nothing more needs sending.

Publishing a port

A port is a plugin built for another firmware by someone other than its author. It is your own plugin, on your own page, which names the original and links to it. You can port a plugin on this site when its author has ticked "Ports welcome" ("ports_welcome": true when you read it, and a note on its page).

POST /api/v1/plugins with the field port_of set to the original, as its owner and link name:

curl -X POST https://oplug1.dev/api/v1/plugins \
  -H "Authorization: Bearer $OPLUG1_TOKEN" \
  -F port_of=alice/test-synth \
  -F summary="Test Synth for op1r." \
  -F source_url=https://github.com/you/test-synth-port \
  -F files=@build/test-synth.op1p \
  -F rights=yes
Field Needed Meaning
port_of yes The original: owner/link-name, the last two parts of its address.
summary yes One line about your port.
source_url yes An https:// link to your port's source code.
files yes At least one file for a firmware the original has no file for.
rights yes yes, as above.
based_on no The version of the original you ported. Left out, it is the original's current version.

The name, type and licence are the original's; sending them changes nothing. slug, version, changelog, description, tags, docs_url, screenshots and audio work as for any plugin. The original's author is told about the port and can take it off their plugin's page. A port cannot itself be ported: port the original.

New releases of your port go to POST /api/v1/plugins/SLUG/releases like any other, and take based_on too.

Publishing a new release

POST /api/v1/plugins/SLUG/releases

Field Needed Meaning
version yes A label this plugin has not used yet.
files yes As above. Repeat the field for several firmwares.
rights yes yes, as above.
changelog no Markdown. What is new in this release.

versions_ and tested_ fields work as above. The plugin's name, description, screenshots and other details are edited on the website.

If the plugin already has a release with that version, the answer has status 409 and "code": "version_exists", and nothing is changed. A script that runs twice can treat that as "already published".

Adding a file to a release

POST /api/v1/plugins/SLUG/files

For the same version built for one more firmware: the file joins the release's other files, and the plugin's page then offers a download for that firmware too. Use a new release instead when the code changed.

Field Needed Meaning
files yes The plugin file. Repeat the field for several. A file the release already has is refused.
rights yes yes, as above.
version no The release to add to. Left out, it is the newest release.
curl -X POST https://oplug1.dev/api/v1/plugins/my-synth/files \
  -H "Authorization: Bearer $OPLUG1_TOKEN" \
  -F files=@build/my-synth.knl \
  -F rights=yes

A file's bytes never change once stored, and a file cannot be removed through the API.

Answers and errors

A request that worked answers with status 200 or 201 and "ok": true. One that did not answers with "ok": false and an error sentence. A refused upload also lists every problem by field, and nothing is stored:

{"ok": false,
 "error": "summary: This field is required. files: notes.txt is not a plugin file. Plugin files end in .knl, .op1p or .opmod.",
 "errors": {"summary": ["This field is required."],
            "files": ["notes.txt is not a plugin file. Plugin files end in .knl, .op1p or .opmod."]}}
Status Meaning
400 The upload was refused. Read errors, fix the fields and send it again.
401 The token is missing, wrong or revoked.
404 You have no plugin with that link name, or the address is wrong.
409 That version already exists ("code": "version_exists").
413 The request is larger than one full upload form.
415 The fields were not sent as multipart/form-data.
429 Too many requests. Wait for the number of seconds in the Retry-After header.

An answer that is not JSON, such as a 403 with error code: 1010, did not come from the API. It came from the network protection in front of the site, which turns away some script tools by their name. Send a User-Agent header that names your tool, for example User-Agent: my-plugin-uploader/1.0. curl and the Python requests library work as they are; Python's built-in urllib needs the header.

Limits

The same as on the website: 20 plugin files and 10 new plugins per account per day, and 100 MB of storage per account. At most 40 uploads or other changes per minute come from one network address. GET /api/v1/me shows what is used.

Notes for scripts and AI assistants

The same upload in Python, with the requests library:

import os, requests

answer = requests.post(
    "https://oplug1.dev/api/v1/plugins/my-synth/releases",
    headers={"Authorization": "Bearer " + os.environ["OPLUG1_TOKEN"]},
    data={"version": "1.1", "changelog": "Fixed the filter envelope.", "rights": "yes"},
    files=[("files", open("build/my-synth.op1p", "rb"))],
)
print(answer.status_code, answer.json())