ParamtuneParamtune

Docs

API docs.

Read and write platform schemas and versions over HTTP.

View OpenAPI spec

Quick start

Go from zero to a resolved schema in four steps.

1

Create a platform

Platforms are top-level containers that group related schema versions. Create one by POSTing to the platform endpoint.

Request
curl -X POST http://localhost:3000/api/mobile \
  -H "Content-Type: application/json" \
  -d '{"name": "mobile", "versions": ["1.0.0"]}'
Response
{ "ok": true }
2

Add a version

Each platform can have multiple versions. Add new versions as your configuration evolves.

Request
curl -X POST http://localhost:3000/api/mobile/versions \
  -H "Content-Type: application/json" \
  -d '{"version": "1.1.0"}'
Response
{ "ok": true }
3

Fetch the resolved schema

Retrieve the fully resolved schema for a specific version. The response includes the raw content, declared dependencies, and the merged output with all inherited values.

Request
curl http://localhost:3000/api/mobile/1.1.0
Response
{
  "content": { "feature": { "enabled": true } },
  "dependencies": ["core/1.0.0"],
  "output": {
    "feature": { "enabled": true },
    "core": { "version": "1.0.0" }
  }
}
4

List everything

Query all platforms at once or drill into a specific platform to see its available versions.

Request
curl http://localhost:3000/api/schemas
Response
[
  { "name": "mobile", "versions": ["1.0.0", "1.1.0"] },
  { "name": "web", "versions": ["2.0.0"] }
]

Schema composition

Inherit, override, and compose schemas across platforms.

@extends directive

Schemas can inherit from other schemas using @extends. The child schema is deep-merged on top of the parent, so you only need to declare overrides.

{
  "@extends": "core/1.0.0",
  "feature": {
    "enabled": true,
    "override": "custom-value"
  }
}

Version ranges

Dependencies can use semver ranges to stay up-to-date without pinning to an exact version. Supported syntaxes include caret (^), tilde (~), and comparison operators.

// Exact version
"@extends": "core/1.2.3"

// Latest available
"@extends": "core/latest"

// Compatible versions (^, ~, >=)
"@extends": "core/^1.0.0"
"@extends": "core/~1.2.0"
"@extends": "core/>=1.0.0"

Cascade updates

When a base schema changes, all schemas that depend on it via @extends are automatically re-resolved. Circular dependencies are detected and rejected at save time.

// If "core/1.0.0" is updated, every schema
// that declares '@extends': 'core/1.0.0'
// (or a matching range) is re-processed
// automatically.

Validation

What gets checked before a schema is saved.

  • Content must be a plain JSON object — arrays, strings, and null are rejected.
  • Every @extends reference must resolve to an existing platform/version pair.
  • Semver ranges must match at least one published version.
  • Circular dependency chains are detected at any depth and rejected with a clear error message.

Error format

All error responses share a consistent shape.

HTTP status codes follow REST conventions: 400 for bad input, 404 for missing resources, and 500 for server failures.

{ "error": "Error message" }