Collection Format

noodle collections are directories of .yml files on disk. This reference covers every field, type, and constraint.

Request File (.yml)

One request per file. Extension must be .yml (not .yaml).

Field	Type	Required	Default	Description
name	string	yes	Required	Display name for the request
method	string	yes	Required	GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url	string	yes	Required	Full URL, supports $VAR substitution
timeout	number	no	0	Request timeout in ms. 0 = no timeout
tags	array	no	[]	Case-sensitive suite tags
followRedirects	boolean	no	true	Follow HTTP redirects
maxRedirects	number	no	5	Max redirect chain length
sendCookies	boolean	no	true	Send matching collection jar cookies; false still captures responses
body_type	string	no	none	none, json, xml, multipart, urlencoded, binary
headers	map	no	{}	Request headers (omit if empty)
params	array	no	[]	URL query parameters (omit if empty)
path_params	array	no	[]	Values for :name URL path tokens (omit if empty)
body	string	no	None	Raw body content
form_data	array	no	None	Multipart form entries
file_path	string	no	None	Path to binary upload file
auth	object	no	None	Auth config (omit for no auth)
tls	object	no	None	Per-request TLS override; supports only `verify: true
capture	map	no	None	Response capture objects for manual and automated runs
assert	array	no	None	Response assertions for manual and automated runs

Suite Tags

Request tags are case-sensitive, non-empty strings with no surrounding whitespace. They combine with tags from every ancestor folder and can filter a collection run without creating another collection:

tags:
  - smoke
  - users

Use --tag smoke to include requests with that effective tag and --exclude-tag destructive to remove matches. Repeated --tag values all must match; any repeated --exclude-tag match removes the request. Exclusion wins when both filter types match.

Headers

Key-value map. Values can be simple strings (enabled) or objects with value and enabled fields:

headers:
  Content-Type: application/json
  Authorization: { value: "Bearer $token", enabled: false }

Params

Array of { name, value, enabled } entries. Each entry:

• name: string, required
• value: string, required
• enabled: boolean, default true

params:
  - name: userId
    value: $user_id
  - name: _limit
    value: "10"
  - name: disabled_param
    value: x
    enabled: false

Path Params

Use :name tokens in the URL and provide one required value for each token in path_params. Path params are substituted before sending, so they do not support enabled: false.

url: $base_url/users/:userId
path_params:
  - name: userId
    value: $user_id

Noodle synchronizes these entries with URL tokens when you edit the URL.

Response Captures

An optional capture mapping assigns response expressions to run variables. Later requests in the same ordered collection run can use transient captures through the normal $VARNAME syntax:

capture:
  user_id:
    value: body.user.id
  access_token:
    value: body.access_token
    persist: secret
  optional_trace:
    value: headers.x-trace
    enabled: false

Variable names must match ^\w+$. Every entry is an object with required string value, optional persist: secret|environment, and optional boolean enabled. Scalar shorthand, unknown fields, and invalid persistence values are rejected. Omitted enabled means enabled and is omitted from canonical YAML. Disabled entries are still validated but produce no result, failure, summary count, RunScope mutation, timeline outcome, or write.

Expressions use status, response.time, case-insensitive headers.<name>, or body followed by dot properties and array indexes. They are validated when the request loads and are never variable-substituted.

Each manual TUI send and request run gets an isolated scope, while one collection run shares a scope across its ordered requests. Environment and secret values load first, then successful captures override values with the same name. The latest successful capture wins. Strings substitute verbatim; numbers, booleans, null, arrays, and objects use their JSON representation.

Captures are evaluated before assertions. Successful values commit even when another capture, the HTTP status, or a later assertion fails. A missing or invalid traversal fails the capture without creating or replacing a variable; the request fails, but a collection run continues in collection order.

Transient values disappear when the call returns and never modify request YAML, collection settings, or timeline history. On a manual TUI send or CLI request run, persist: environment writes an enabled plaintext value and refuses to downgrade an existing secret; persist: secret stores the value in the OS vault and writes only a blank secret declaration. An active or selected environment is required. Persistence keeps partial successes, and a failed write fails that capture without discarding the HTTP response. CLI collection run and the TUI Runner ignore persistence. Secret capture values are always fully redacted from results.

Response Assertions

An optional assert list validates responses from manual TUI sends, request run, and collection run. Manual outcomes appear in Results; a failed assertion makes automation commands fail.

assert:
  - expression: status
    operator: equals
    value: 200
  - expression: body.users[0].id
    operator: isNumber
  - expression: headers.Content-Type
    operator: contains
    value: application/json
  - expression: response.time
    operator: lt
    value: 500
    enabled: false

Each assertion accepts optional boolean enabled; omitted means enabled and is omitted from canonical YAML. Disabled assertions remain validated and editable but are not substituted, evaluated, or included in results, failures, summaries, or timeline assertion outcomes.

Expressions are status, response.time, headers.<name> with case-insensitive header lookup, or body followed by dot properties and array indexes. Body expressions require valid JSON.

Operators without value: exists, notExists, isString, isNumber, isBoolean, isArray, isObject, isNull, notNull.

Operators with a JSON-compatible value: equals, notEquals, gt, gte, lt, lte, contains, notContains, matches. Numeric comparisons require finite numbers. Containment checks string substrings or deeply equal array members. matches accepts strings and a restricted JavaScript regular-expression subset that rejects backreferences, groups, alternation, braced quantifiers, and unsafe repetition.

String values recursively support $VARNAME substitution; expressions and operators do not. Expected secret values are redacted from run results. JSON output includes actual server values, so treat assertion results as sensitive response data.

Form Data

Array for multipart and urlencoded body types. Each entry:

• name: string, required
• value: string, required
• type: text (default) or file
• enabled: boolean, default true

body_type: multipart
form_data:
  - name: description
    value: A photo
  - name: file
    value: ./photo.png
    type: file

For urlencoded, use the same entries with text values; omit type or set it to text.

File Path Shorthand

Multipart file entries and binary file_path values can use a quoted @/ prefix for the current user’s home directory:

file_path: '@/Documents/photo.png'

Noodle keeps this portable shorthand in the collection and expands it only when reading an upload file or producing an output artifact. Postman exports therefore contain absolute file paths and should be reviewed for local-path disclosure before sharing.

XML Body

XML bodies are sent unchanged after environment-variable substitution. Noodle adds Content-Type: application/xml when no enabled Content-Type header exists; set an explicit header for MIME types such as text/xml or application/soap+xml.

body_type: xml
body: |-
  <request>
    <id>$request_id</id>
  </request>

Auth

Type	Fields	Description
none	None	No auth (omit auth field entirely)
inherit	None	Use nearest parent folder’s auth
bearer	token	Bearer token auth
basic	user, pass	Basic auth
ntlm	username, password, optional domain, workstation	Connection-bound server NTLMv2 auth
api_key	key, value, placement	API key auth. placement: header or query
aws_sigv4	access_key, secret_key, region, service, session_token	AWS Signature Version 4; session_token is optional
oauth1	consumer_key, consumer_secret, access_token, access_token_secret, signing and placement fields	OAuth 1.0a request signing
oauth2	grant, endpoint, client, token lifecycle, client assertion, delivery, and additional parameter fields	OAuth 2.0 secure token workflow

auth:
  type: bearer
  token: $api_token

NTLM uses the server’s connection-bound NTLMv2 challenge exchange. Proxy NTLM, NTLMv1, Kerberos/SPNEGO negotiation, signing, sealing, and channel binding are not supported. AWS SigV4 signs requests after variable substitution and supports text, JSON, URL-encoded, and binary bodies; multipart is not supported. Keep passwords, AWS secret keys, and session tokens in secret environment variables.

OAuth 1.0a

auth:
  type: oauth1
  consumer_key: $oauth1_consumer_key
  consumer_secret: $oauth1_consumer_secret
  access_token: $oauth1_access_token
  access_token_secret: $oauth1_access_token_secret
  signature_method: HMAC-SHA256
  private_key: ""
  private_key_type: text
  callback_url: ""
  verifier: ""
  timestamp: ""
  nonce: ""
  version: "1.0"
  realm: ""
  placement: header
  include_body_hash: false

signature_method supports HMAC-SHA1/256/512, RSA-SHA1/256/512, and PLAINTEXT; the default is HMAC-SHA1. RSA keys may be inline text or a collection-relative or @/ file. placement is header, query, or body; body placement requires URL-encoded form data. Blank timestamp and nonce values are generated for each signature. include_body_hash: true does not support multipart bodies, and PLAINTEXT is limited to HTTPS or loopback HTTP.

OAuth 2.0

auth:
  type: oauth2
  grant_type: authorization_code
  authorization_url: https://identity.example.com/oauth/authorize
  access_token_url: https://identity.example.com/oauth/token
  refresh_token_url: https://identity.example.com/oauth/token
  client_id: $oauth2_client_id
  client_secret: $oauth2_client_secret
  username: ""
  password: ""
  scope: openid profile
  audience: https://api.example.com
  redirect_uri: http://127.0.0.1:8765/oauth/callback
  credentials_id: example-api
  auto_fetch_token: true
  auto_refresh_token: true
  pkce: true
  pkce_method: S256
  implicit_response_type: token
  credentials_placement: body
  client_authentication: client_secret
  client_assertion_algorithm: RS256
  client_assertion_key: ""
  client_assertion_key_type: text
  client_assertion_issuer: ""
  client_assertion_subject: ""
  client_assertion_audience: ""
  client_assertion_lifetime: 300
  token_source: access_token
  token_placement: header
  token_header: Authorization
  token_prefix: Bearer
  token_query_key: access_token
  additional_parameters:
    authorization:
      - name: prompt
        value: consent
        enabled: true
        placement: query
    token: []
    refresh: []

grant_type is authorization_code, client_credentials, implicit, or password. Authorization code defaults to S256 PKCE; pkce_method may also be plain. implicit_response_type is token, id_token, or token id_token. credentials_placement is body or basic. credentials_id is an optional stable key for sharing compatible stored token state.

For signed client authentication, set client_authentication to client_assertion. Assertion algorithms are HS, RS, PS, or ES with 256, 384, or 512 suffixes. client_assertion_key_type is text or file, and the lifetime must be a positive integer. Issuer, subject, and audience are optional overrides.

token_source is access_token or id_token. token_placement is header or query, with customizable header, prefix, and query key. Authorization additional parameters use query placement. Token and refresh parameters may use body, header, or query placement; each entry has name, value, optional enabled, and placement.

OAuth endpoints require HTTPS except on loopback hosts. Browser flows use a loopback HTTP callback ending in /oauth/callback. Token responses are stored in the OS credential vault or kept in memory for the current session when the vault is unavailable; they are never serialized to request YAML.

TLS override

A request can override only certificate verification:

tls:
  verify: false

Omit tls to inherit the collection setting. CA bundles and client certificates are collection settings, not request fields.

Minimal Request

name: My Request
method: GET
url: $base_url/endpoint
timeout: 0

Folder File (folder.yml)

Optional. Defines display name, sort order, suite tags, and inheritable overrides.

meta:
  name: Users
  seq: 1
tags:
  - smoke
headers:
  X-Custom: value
auth:
  type: bearer
  token: $folder_token

Field	Type	Required	Description
meta	object	no	Display metadata
meta.name	string	no	Display name (defaults to directory name)
meta.seq	number	no	Sort order (lower = first, undefined = last)
tags	array	no	Suite tags inherited by descendants
headers	map	no	Inherited headers (merge additively)
auth	object	no	Inherited auth

Inheritance

• Tags: Request tags combine with every ancestor folder’s tags. Duplicates have no additional effect, descendants cannot remove inherited tags, and a root-level folder.yml is ignored.
• Headers: Folder headers merge additively. Request’s headers win on same key.
• Auth: Requests with type: inherit use nearest ancestor folder’s auth. Walk tree from child up.

Collection Settings (settings.yml)

Single file at collection root:

collection_id: 123e4567-e89b-42d3-a456-426614174000
name: Payments API
description: |-
  Requests for the payments platform.
timeline_max_entries: 50
environment: development
cookies:
  enabled: true
proxy:
  mode: custom
  url: http://proxy.example:8080
  bypass: [localhost, .internal.example]
  auth: true
tls:
  verify: true
  ca_bundle: ./certs/internal-roots.pem
  client_certificates:
    - host: api.internal.example
      port: 443
      cert_file: ./certs/client-chain.pem
      key_file: ./certs/client-key.pem
      secret_id: 123e4567-e89b-42d3-a456-426614174001

Field	Type	Description
collection_id	UUID string	Generated credential-vault namespace. Preserve it when moving a collection; do not copy it into another collection.
name	string	Optional display name; defaults to the collection directory name.
description	string	Optional collection notes.
timeline_max_entries	non-negative integer	Per-request history retention. Defaults to 50; 0 disables recording.
environment	string	Default active environment. Must match a .env file in .environments/.
cookies	object	Optional cookie policy. enabled is a boolean and defaults to true; false prevents sending and capturing jar cookies.
proxy	object	Optional collection proxy policy. mode is inherit, off, or custom. A custom policy uses an http or https url and an optional string-array bypass list.
tls	object	Optional TLS policy with verify, ca_bundle, and exact-host client_certificates.

Custom proxy URLs reject credentials and variables. When authentication is enabled, auth: true is persisted while the username and optional password live in the OS credential vault. --noproxy forces direct connections for one TUI, collection run, or request run invocation. See Settings for proxy scope, precedence, and bypass rules.

TLS client-certificate profiles require host, cert_file, and key_file; port defaults to 443, and enabled is optional. Relative paths resolve from the collection root. Enter encrypted-key passphrases in Settings; Noodle stores them in the OS vault and persists only the generated secret_id. Use --insecure to disable verification for one invocation.

Settings are validated strictly. Malformed YAML, unknown keys, wrong types, and invalid proxy/TLS/cookie blocks fail collection opening, auditing, and automation. A missing or empty file uses defaults.

Redirects follow only HTTP or HTTPS. Noodle rejects HTTPS-to-HTTP downgrades and removes authorization, proxy authorization, cookies, Host, and header API-key credentials before following a cross-origin redirect.

Hidden State (.noodle/)

Auto-generated files managed by noodle:

File	Format	Purpose
last-request	Plain text	Last selected request ID
expanded-folders	YAML list	Expanded folder paths in sidebar
ui-state/<requestId>.yml	YAML	Per-request tab index state