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
- Read the token from the
OPLUG1_TOKENenvironment variable. Never write it into a file that is committed, and never print it. - Start with
GET /api/v1/me. It confirms the token and lists the plugins that already exist, so you know whether to publish a new plugin or a new release. - Before publishing a release, compare your version with
latest_version. Sending the same version again is refused with status 409. - A new plugin cannot be removed or renamed through the API, and its link name is permanent. Check the name, link name and type with the author before the first upload.
- Uploads are public at once. Only send files the author asked you to publish.
- On Windows PowerShell, call
curl.exe, notcurl. - Send requests one after another, not side by side.
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())