Collection JSON Schema — API Studio Docs

File Structure

// .openpost/collections.json
[
  {
    "id": "uuid-v4",
    "name": "My API",
    "description": "Optional markdown description",
    "folders": [ /* CollectionFolder[] */ ],
    "requests": [ /* ApiRequest[] */ ],
    "variables": [ /* KeyValue[] */ ],
    "auth": { /* AuthConfig */ },
    "certificateConfig": { /* CertificateConfig */ },
    "preRequestScript": "// JS code",
    "testScript": "// JS code"
  }
]

Collection

Field	Type	Required	Description
id	string	✓	UUID v4 unique identifier
name	string	✓	Display name
description	string		Markdown description shown in collection editor Overview tab
folders	CollectionFolder[]	✓	Nested folders. Array index = display order
requests	ApiRequest[]	✓	Top-level requests. Array index = display order
variables	KeyValue[]	✓	Collection-scoped variables (lowest priority in resolution chain)
auth	AuthConfig		Collection-level auth inherited by children
certificateConfig	CertificateConfig		TLS client certificates at collection level
preRequestScript	string		JavaScript that runs before each inherited request
testScript	string		JavaScript that runs after each inherited request

CollectionFolder

Field	Type	Required	Description
id	string	✓	UUID v4
name	string	✓	Folder name
requests	ApiRequest[]	✓	Requests in this folder
folders	CollectionFolder[]	✓	Recursive child folders (unlimited depth)
auth	AuthConfig		Folder-level auth
inheritAuth	boolean		Inherit auth from parent folder/collection
certificateConfig	CertificateConfig		TLS certs at folder level
inheritCertificate	boolean		Inherit certificates from parent
preRequestScript	string		Pre-request JS for this folder
testScript	string		Test JS for this folder
inheritScripts	boolean		Inherit scripts from parent (concatenated)

ApiRequest

Field	Type	Req	Description
id	string	✓	UUID v4
name	string	✓	Display name
method	string	✓	HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, or custom)
url	string	✓	URL (may contain {{variable}} placeholders)
params	KeyValue[]	✓	Query parameters
headers	KeyValue[]	✓	Request headers
body	RequestBody	✓	Request body configuration
auth	AuthConfig	✓	Auth configuration
inheritAuth	boolean		Inherit from parent (default: false)
inheritScripts	boolean		Inherit scripts from parent
inheritCertificate	boolean		Inherit TLS certs from parent
preRequestScript	string		Pre-request JavaScript
testScript	string		Test JavaScript
testRules	TestRule[]		GUI assertion rules
setVariables	SetVariable[]		Response extraction rules
proxyId	string		References a ProxyConfig.id
certificateConfig	CertificateConfig		Per-request TLS certificates
mcpDescription	string		Description when exposed as MCP tool
mcpInputSchema	object		JSON Schema for MCP tool parameters
isSSE	boolean		Force SSE streaming mode
grpcConfig	GrpcConfig		gRPC call configuration

RequestBody

Field	Type	Description
type	"none" \| "json" \| "raw" \| "xml" \| "graphql" \| "form-data" \| "x-www-form-urlencoded" \| "binary"	Body type selector
raw	string	Content for json, raw, or xml types
formData	KeyValue[]	Text fields for form-data / urlencoded
formDataFiles	FormDataItem[]	File fields for multipart form-data
graphql	GraphQLBody	GraphQL query, variables, and operation name
binaryPath	string	Absolute path to binary file
binaryName	string	Display filename for binary

AuthConfig

{
  "type": "none" | "basic" | "bearer" | "api-key" | "oauth2" | "aws-sigv4" | "digest",
  "basic": { "username": "string", "password": "string" },
  "bearer": { "token": "string" },
  "apiKey": { "key": "string", "value": "string", "addTo": "header" | "query" },
  "oauth2": {
    "grantType": "authorization_code" | "client_credentials",
    "authUrl": "string", "tokenUrl": "string",
    "clientId": "string", "clientSecret": "string",
    "scope": "string", "accessToken": "string"
  },
  "awsSigV4": { "accessKey": "string", "secretKey": "string", "region": "string", "service": "string" },
  "digest": { "username": "string", "password": "string" }
}

Only the sub-object matching type needs to be present. All string values support {{variable}} interpolation.

KeyValue

{ "key": "string", "value": "string", "enabled": true | false }

Used for params, headers, form fields, environment variables, and collection variables. Disabled entries are stored but not sent.

FormDataItem

{ "key": "string", "value": "string", "enabled": true, "fieldType": "text" | "file", "filePath": "/path", "fileName": "file.png" }

GraphQLBody

{ "query": "query { users { id name } }", "variables": "{}", "operationName": "GetUsers", "schemaUrlOverride": "https://..." }

variables is a JSON string. operationName is only needed when the document contains multiple operations.

TestRule

{
  "id": "uuid",
  "source": "status" | "time" | "size" | "body" | "jsonpath" | "header" | "content-type" | "content-length" | "body-contains" | "body-is-json" | "body-schema",
  "property": "$.data.id",      // JSONPath expression, header name, or empty
  "operator": "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "not-contains" | "matches" | "not-matches" | "is-empty" | "is-not-empty" | "exists" | "not-exists" | "is-type",
  "expected": "200",
  "enabled": true
}

SetVariable

{
  "id": "uuid",
  "source": "jsonpath" | "header" | "body" | "regex",
  "property": "$.token",         // JSONPath, header name, or regex pattern
  "variableName": "auth_token",  // saved to active environment
  "enabled": true
}

CertificateConfig

{ "clientCertId": "vault-entry-id", "privateKeyId": "vault-entry-id", "caBundleId": "vault-entry-id" }

References CertificateEntry.id values stored in the encrypted vault.

GrpcConfig

{
  "protoFilePath": "/path/to/service.proto",
  "protoFileName": "service.proto",
  "serviceName": "UserService",
  "methodName": "GetUser",
  "useReflection": false,
  "callType": "unary" | "server-streaming",
  "messageBody": "{ \"id\": 1 }"
}

Full Example

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "User API",
    "description": "# User Service\nCRUD operations for user management.",
    "variables": [
      { "key": "base_url", "value": "https://api.example.com", "enabled": true }
    ],
    "auth": { "type": "bearer", "bearer": { "token": "{{api_token}}" } },
    "preRequestScript": "request.headers.push({ key: 'X-Request-Id', value: crypto.randomUUID(), enabled: true });",
    "testScript": "",
    "folders": [
      {
        "id": "f1f2f3f4-0000-0000-0000-000000000001",
        "name": "Users",
        "inheritAuth": true,
        "inheritScripts": true,
        "folders": [],
        "requests": [
          {
            "id": "r1r2r3r4-0000-0000-0000-000000000001",
            "name": "Get User",
            "method": "GET",
            "url": "{{base_url}}/users/{{user_id}}",
            "params": [],
            "headers": [
              { "key": "Accept", "value": "application/json", "enabled": true }
            ],
            "body": { "type": "none" },
            "auth": { "type": "none" },
            "inheritAuth": true,
            "testRules": [
              { "id": "t1", "source": "status", "property": "", "operator": "eq", "expected": "200", "enabled": true }
            ],
            "setVariables": [
              { "id": "sv1", "source": "jsonpath", "property": "$.name", "variableName": "user_name", "enabled": true }
            ]
          }
        ]
      }
    ],
    "requests": []
  }
]