OpenAPI 3.1 specification for the Rclone RC API.
Each release describes exactly one rclone version, and the package version matches it.
npm install rclone-openapi
// ESM import schema from 'rclone-openapi'; // CommonJS const schema = require('rclone-openapi');
You can also import the JSON file directly. In Node ESM, this needs the import attribute:
import schema from 'rclone-openapi/openapi.json' with { type: 'json' };
The YAML version is available at rclone-openapi/openapi.yaml:
const path = require.resolve('rclone-openapi/openapi.yaml');
This package includes generated TypeScript types for the Rclone RC API:
import type { paths, operations, components } from 'rclone-openapi'; // Example: Type for the /config/listremotes response type ListRemotesResponse = paths['/config/listremotes']['post']['responses']['200']['content']['application/json']; // Example: Type for a request body type CopyFileBody = NonNullable<operations['operationsCopyfile']['requestBody']>['content']['application/json']; // Example: Calls running in the background return 202 with a job ID type AsyncJob = components['responses']['AsyncJobResponse']['content']['application/json'];
Works great with API clients like openapi-fetch:
import createClient from 'openapi-fetch'; import type { paths } from 'rclone-openapi'; const client = createClient<paths>({ baseUrl: 'http://localhost:5572' }); // A call with no required fields const { data, error } = await client.POST('/config/listremotes'); // Fields go in the JSON body const { data: status } = await client.POST('/job/status', { body: { jobid: 1 } }); // Run a call in the background, which returns 202 with { jobid } const { data: job, response } = await client.POST('/sync/copy', { body: { srcFs: 'drive:src', dstFs: 'drive:dst' }, params: { header: { Prefer: 'respond-async' } }, });
data is typed as either the 200 body or the 202 body, because the header doesn't narrow it. Check response.status or 'jobid' in data before using it.
openapi-fetch doesn't reject extra body fields, so a misspelled optional field still compiles.
POSTcommands with JSON bodies. Rclone also accepts the same params in the query string or a form-encoded body. The spec leaves those out, so that each field has one documented form andrequiredcan be enforced.operations/uploadfileis the exception. Its params can only go in the query string, because rclone doesn't read them from a multipart body.Prefer: respond-asyncis how to run a call in the background. Rclone's_asyncparam has the same effect, but on its own it returns a 200 with the job ID rather than the route's normal body. Routes don't list it for that reason.job/batchinputs have no headers, so they use_async.
| File | Description |
|---|---|
openapi.yaml |
OpenAPI 3.1 specification. This is the file to edit. |
openapi.json |
Generated JSON version of the specification |
types.d.ts |
Generated TypeScript type definitions |
index.mjs |
Generated ESM entry point |
index.d.mts, index.d.cts, document.d.ts |
Type definitions for the entry points |
Edit openapi.yaml, then regenerate the other files. This also copies the version from package.json into the spec:
npm run gen
Check the result. This needs Go for the source audit:
npm run check # Runs lint and all of the checks below, except check:package npm run check:types # Compiles real openapi-fetch calls against the types npm run check:contract # Tests the spec against the rclone release for this version npm run check:source # Compares the spec with the source of that rclone release npm run check:package # Installs the packed package and tests every import above
check:contract and check:source download rclone into .work/cache, which git ignores. Set OPENAPI_RCLONE_VERSION to check another version, such as latest. Set OPENAPI_RCLONE_BIN to test a local rclone binary.
npm run bump -- 1.75.3 # Use the rclone version npm run gen git commit -am "bump to 1.75.3" npm run pub # Regenerates, runs every check, then publishes git tag v1.75.3
Always publish with npm run pub. Plain npm publish skips the checks.
- Rclone SDK — Ready-to-use client built on this spec (supports Rust and Javascript/Typescript)
- Rclone RC API Documentation
- Rclone — Cloud storage sync tool
MIT