# oplug1 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 , 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 . 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 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=