Rostyman Collection Format

Rostyman uses its own JSON-based .rostyman format for exporting and importing collections. This format captures everything in a single file: requests, folders, variables, environments, auth, scripts, and examples.

This is an open, documented format — any tool is free to read and write it. A machine-readable JSON Schema is published for validation and code generation. To bundle multiple collections together with workspace-level assets (mock servers, workflows, scheduled jobs, globals, vault secrets, browser tests, and database connections), see the Rostyman Workspace Format.

Overview

Property	Value
File extension	`.rostyman` or `.json`
MIME type	`application/json`
Encoding	UTF-8
Version	`1.0`

Top-Level Structure

{
  "_type": "rostyman_collection",
  "_version": "1.0",
  "info": {
    "name": "My API Collection",
    "description": "Optional description",
    "exportedAt": "2026-03-25T12:00:00.000Z",
    "exportedFrom": "Rostyman 0.1.0-beta.9"
  },
  "auth": { ... },
  "preScript": "// runs before every request",
  "testScript": "// runs after every response",
  "variables": [ ... ],
  "environments": [ ... ],
  "items": [ ... ]
}

Required Fields

_type — must be "rostyman_collection"
_version — format version (currently "1.0")
info.name — collection name

Optional Fields

info.description — collection description
info.exportedAt — ISO 8601 timestamp
info.exportedFrom — Rostyman version that created the file
auth — collection-level authentication
preScript — JavaScript that runs before all requests
testScript — JavaScript that runs after all responses
variables — collection-scoped variables
environments — named variable sets
items — folders and requests (recursive tree)

Items (Requests & Folders)

Items form a recursive tree. Each item is either a request or a folder.

Request

{
  "type": "request",
  "name": "Get Users",
  "description": "Fetch paginated user list",
  "method": "GET",
  "url": "{{baseUrl}}/api/users",
  "params": [
    { "key": "page", "value": "1", "enabled": true, "description": "Page number" },
    { "key": "limit", "value": "20", "enabled": true, "description": "" }
  ],
  "headers": [
    { "key": "Accept", "value": "application/json", "enabled": true, "description": "" }
  ],
  "body": {
    "mode": "none"
  },
  "auth": { "type": "inherit" },
  "preScript": "",
  "testScript": "rm.test('Status is 200', () => rm.expect(rm.response.code).to.equal(200));",
  "examples": []
}

Supported methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

Folder

{
  "type": "folder",
  "name": "Users",
  "description": "User management endpoints",
  "items": [
    { "type": "request", "name": "Get Users", ... },
    { "type": "folder", "name": "Admin", "items": [ ... ] }
  ]
}

Folders can nest to any depth.

Protocol Items

Besides request and folder, an item's type can be one of the streaming / RPC / agent protocols below. Each is a leaf item (no nested items). Like HTTP requests, they support {{variable}} placeholders in their URLs and headers.

SSE (Server-Sent Events)

{
  "type": "sse",
  "name": "Live Prices",
  "method": "GET",
  "url": "{{baseUrl}}/stream",
  "params": [],
  "headers": [],
  "body": "{ \"channel\": \"prices\" }",
  "bodyLanguage": "json"
}

method is GET or POST. body and bodyLanguage apply to POST only.

WebSocket

{
  "type": "websocket",
  "name": "Echo",
  "url": "wss://echo.websocket.org",
  "params": [],
  "headers": []
}

Socket.IO

{ "type": "socketio", "name": "Realtime", "url": "wss://example.com" }

MQTT

{ "type": "mqtt", "name": "Broker", "url": "mqtt://test.mosquitto.org:1883" }

gRPC

{ "type": "grpc", "name": "Greeter", "url": "grpc.example.com:50051" }

MCP (Model Context Protocol)

{
  "type": "mcp",
  "name": "Filesystem Server",
  "transport": "stdio",
  "input": "npx -y @modelcontextprotocol/server-filesystem /data",
  "authToken": "",
  "envVars": [ { "key": "ROOT", "value": "/data", "enabled": true } ],
  "timeout": 0
}

transport is stdio (then input is the command line) or sse (then input is the server URL).

Body

{
  "mode": "raw",
  "raw": "{ \"name\": \"John\" }",
  "language": "json"
}

Mode	Fields	Description
`none`	—	No body
`raw`	`raw`, `language`	Raw text body
`formdata`	`formdata[]`	Multipart form data
`urlencoded`	`urlencoded[]`	URL-encoded form
`graphql`	`graphql.query`, `graphql.variables`	GraphQL query
`binary`	—	File body. Only the `mode` is exported — the local file path is not portable, so re-attach the file after import.

Raw languages: json, xml, html, text, javascript, graphql

Form Data / URL-Encoded

{
  "mode": "formdata",
  "formdata": [
    { "key": "file", "value": "/path/to/file.png", "enabled": true, "description": "Upload" },
    { "key": "name", "value": "photo.png", "enabled": true, "description": "" }
  ]
}

GraphQL

{
  "mode": "graphql",
  "graphql": {
    "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
    "variables": "{ \"id\": \"123\" }"
  }
}

Authentication

{ "type": "none" }
{ "type": "inherit" }
{ "type": "bearer", "bearer": { "token": "{{accessToken}}" } }
{ "type": "basic", "basic": { "username": "admin", "password": "{{password}}" } }
{ "type": "api-key", "apikey": { "key": "X-API-Key", "value": "{{apiKey}}", "in": "header" } }

All auth types: none, inherit, bearer, basic, api-key, oauth2, oauth1, digest, aws, ntlm, hawk, jwt, edgegrid, asap

OAuth 2.0

{
  "type": "oauth2",
  "oauth2": {
    "grantType": "authorization_code",
    "authUrl": "https://auth.example.com/authorize",
    "tokenUrl": "https://auth.example.com/token",
    "clientId": "my-app",
    "clientSecret": "{{clientSecret}}",
    "scope": "read write",
    "redirectUri": "https://localhost/callback",
    "token": ""
  }
}

Grant types: authorization_code, authorization_code_pkce, client_credentials, password, implicit

Other auth types

Each type stores its config under a sub-object named after the type. The fields below match how Rostyman and the rosty-cli runner sign requests — all are implemented identically in both.

{ "type": "oauth1",   "oauth1":   { "consumerKey": "", "consumerSecret": "", "token": "", "tokenSecret": "", "signatureMethod": "HMAC-SHA1" } }
{ "type": "digest",   "digest":   { "username": "", "password": "" } }
{ "type": "aws",      "aws":      { "accessKeyId": "", "secretAccessKey": "", "region": "us-east-1", "service": "execute-api", "sessionToken": "" } }
{ "type": "ntlm",     "ntlm":     { "username": "", "password": "", "domain": "", "workstation": "" } }
{ "type": "hawk",     "hawk":     { "authId": "", "authKey": "", "algorithm": "sha256", "user": "", "nonce": "", "ext": "" } }
{ "type": "jwt",      "jwt":      { "algorithm": "HS256", "secret": "", "privateKey": "", "isSecretBase64Encoded": false, "payload": "{}", "headerPrefix": "Bearer", "addTokenTo": "header", "queryParamKey": "token" } }
{ "type": "edgegrid", "edgegrid": { "accessToken": "", "clientToken": "", "clientSecret": "", "headersToSign": "" } }
{ "type": "asap",     "asap":     { "alg": "RS256", "kid": "", "iss": "", "aud": "", "sub": "", "exp": "3600", "privateKey": "", "claims": "{}" } }

Type	Algorithm / scheme
`oauth1`	OAuth 1.0 — `signatureMethod` is `HMAC-SHA1` or `PLAINTEXT`
`digest`	HTTP Digest (401-challenge handshake)
`aws`	AWS Signature v4
`ntlm`	NTLMv2 (3-message handshake)
`hawk`	Hawk MAC — `algorithm` is `sha256` or `sha1`
`jwt`	JWT Bearer — HS/RS/ES/PS families; `addTokenTo` is `header` or `query`
`edgegrid`	Akamai EdgeGrid (EG1-HMAC-SHA256)
`asap`	Atlassian ASAP (RS256 JWT)

Variables

Collection-scoped variables available to all requests:

"variables": [
  {
    "key": "baseUrl",
    "value": "https://api.example.com",
    "type": "text",
    "enabled": true,
    "description": "API base URL"
  },
  {
    "key": "apiSecret",
    "value": "sk-...",
    "type": "secret",
    "enabled": true,
    "description": "API secret key"
  }
]

Types: text (default), secret (masked in UI)

Environments

Named variable sets for switching between configurations:

"environments": [
  {
    "name": "Local",
    "variables": [
      { "key": "baseUrl", "value": "http://localhost:3000", "type": "text", "enabled": true, "description": "" },
      { "key": "token", "value": "dev-token-123", "type": "secret", "enabled": true, "description": "" }
    ]
  },
  {
    "name": "Production",
    "variables": [
      { "key": "baseUrl", "value": "https://api.example.com", "type": "text", "enabled": true, "description": "" },
      { "key": "token", "value": "", "type": "secret", "enabled": true, "description": "Set before use" }
    ]
  }
]

Examples

Saved response examples for documentation:

"examples": [
  {
    "name": "Success",
    "statusCode": 200,
    "statusText": "OK",
    "headers": { "content-type": "application/json" },
    "body": "{ \"success\": true, \"data\": [] }"
  },
  {
    "name": "Unauthorized",
    "statusCode": 401,
    "statusText": "Unauthorized",
    "headers": { "content-type": "application/json" },
    "body": "{ \"error\": \"Invalid token\" }"
  }
]

Scripts

preScript and testScript (at the collection, folder, and request level) are JavaScript using Rostyman's rm.* runtime — rm.environment, rm.collectionVariables, rm.globals, rm.response, rm.test(), rm.expect(). See Pre-request scripts and Test scripts for the full API.

Importers: Postman pm.* scripts are equivalent — Rostyman auto-migrates pm.* → rm.* on import. If you write a converter for another tool, map its scripting calls to rm.*.

Format detection

To detect a Rostyman file, parse the JSON and check _type:

const data = JSON.parse(fileContent)
if (data._type === 'rostyman_collection') { /* a collection — data._version is "1.0" */ }
if (data._type === 'rostyman_workspace')  { /* a workspace */ }

Machine-readable schema

A JSON Schema (draft 2020-12) is published so other tools can validate .rostyman files or generate types:

Collection: https://docs.rostyman.com/schema/rostyman-collection-1.0.schema.json
Workspace: https://docs.rostyman.com/schema/rostyman-workspace-1.0.schema.json

Add "$schema" to a file to get editor validation:

{
  "$schema": "https://docs.rostyman.com/schema/rostyman-collection-1.0.schema.json",
  "_type": "rostyman_collection",
  "_version": "1.0",
  "info": { "name": "My API" },
  "items": []
}

The schemas leave additionalProperties open on purpose — importers ignore unknown fields, so a newer export still validates and still imports in an older reader.

Design Principles

No internal IDs — database IDs are never exported. New IDs are generated on import.
Variables as placeholders — {{baseUrl}} is exported literally, never resolved.
Single file — everything (requests, folders, variables, environments, auth, scripts, examples) in one JSON file.
Pretty-printed — 2-space indentation for readability and clean diffs.
Forward-compatible — the importer ignores unknown fields, so newer exports can be read by older versions.
Deterministic — fields are always in the same order for consistent diffs.

Exporting

Right-click a collection in the sidebar
Select Export
Choose Rostyman JSON format
Save the .rostyman file

Importing

Click Import in the sidebar header
Select your .rostyman file
Rostyman creates a new collection with all folders, requests, variables, environments, and scripts preserved

The importer also supports Postman (v2.1), Insomnia, OpenAPI, HAR, Thunder Client, Hoppscotch, Bruno, and cURL.

Overview​

Top-Level Structure​

Required Fields​

Optional Fields​

Items (Requests & Folders)​

Request​

Folder​

Protocol Items​

SSE (Server-Sent Events)​

WebSocket​

Socket.IO​

MQTT​

gRPC​

MCP (Model Context Protocol)​

Body​

Form Data / URL-Encoded​

GraphQL​

Authentication​

OAuth 2.0​

Other auth types​

Variables​

Environments​

Examples​

Scripts​

Format detection​

Machine-readable schema​

Design Principles​

Exporting​

Importing​