Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JonathanHerSa/xolo-api-hub/llms.txt

Use this file to discover all available pages before exploring further.

Post-response scripts close the loop between an API response and your next request. After every successful HTTP call, Xolo evaluates a set of JSONPath extraction rules against the response body and stores the matched values as environment variables. This is how you implement request chaining — for example, authenticating with a login endpoint, capturing the returned access token, and automatically injecting it as a Bearer header in every subsequent request — without any manual copy-and-paste.

​
Script Format

Post-response scripts are stored as a JSON array on the request record (column scriptsJson). Each element is an object with two fields:
FieldTypeDescription
keyStringThe environment variable name to store the extracted value under
pathStringA JSONPath expression evaluated against the response body
[
  { "key": "authToken", "path": "$.token" },
  { "key": "userId",    "path": "$.data.id" }
]
Rules with an empty key or empty path are silently skipped.

​
JSONPath Syntax

Xolo uses the json_path Dart package for JSONPath evaluation. Expressions follow standard JSONPath notation:
PatternMeaning
$.fieldTop-level field named field
$.nested.fieldNested field access
$.array[0].fieldFirst element of an array, then a field
$.items[*].idAll id values across every element of items
When a path matches multiple nodes, ScriptExecutor uses the first match. If the path matches nothing, the variable is set to the sentinel value '[No Match]' rather than being omitted, so you can immediately see in the UI that the extraction failed.

​
ScriptExecutor.testPostScripts() Signature

/// Tests post-response script rules without persisting variables.
///
/// [responseData]  The parsed response body (Map, List, or primitive)
///                 as decoded by Dio from the JSON response.
/// [scriptsJson]   JSON string containing the array of {key, path} rules.
///
/// Returns a Map<String, String> mapping each variable name to the
/// extracted value (or '[No Match]' if the path did not match,
/// or '[Error: ...]' if the JSONPath expression was invalid).
static Map<String, String> testPostScripts(
  dynamic responseData,
  String scriptsJson,
)
This method is intentionally non-persisting — it is used by the Scripts tab’s Test button and by unit tests. The actual persistence path (CollectionRunnerService._applyPostScripts()) calls XoloRepository.upsertVariable() for every successfully matched value.

​
Live Testing

The Scripts tab provides a Test button (▶) in the Post-Request section header. Tapping it calls testPostScripts() against the most recently received response body — the request is not re-sent. Each extraction rule row displays the matched result inline beneath it, highlighted in orange for a match or red for an error, so you can iterate on your JSONPath expressions rapidly without consuming API rate limits.
Test your JSONPath expressions in the Scripts tab before running a full collection — the inline result shows the extracted value without re-sending. This is especially useful when the endpoint you are extracting from is rate-limited or has side effects.

​
Request Chaining

When you send a request from the composer, successfully matched values are upserted into the active environment via XoloRepository.upsertVariable(). This means subsequent requests in the same session will resolve {{authToken}} (or whatever key you chose) from the environment automatically, without any additional configuration. A complete token-chaining workflow looks like this: 
// POST /auth/login  →  post-response scripts:
[
  { "key": "authToken", "path": "$.access_token" },
  { "key": "currentUserId", "path": "$.user.id" }
]
After the login request completes, authToken and currentUserId are live in the environment. Any subsequent request can reference them: 
GET {{baseUrl}}/users/{{currentUserId}}/profile
Authorization: Bearer {{authToken}}
No manual environment editing is needed between the two requests.

​
Collection Runner Integration

When the collection runner executes a step, post-scripts run after assertions are evaluated and before the next step begins. Extracted values are merged into the shared workingVars map that flows through the entire run: 
// Inside CollectionRunnerService.execute() — simplified
final preVars = ScriptExecutor.executePreScripts(req.preScriptsJson, workingVars);
workingVars.addAll(preVars);

final output = await _pipeline.send(..., variables: workingVars, ...);

// assertions evaluated here...

final extracted = await _applyPostScripts(
  scriptsJson: req.scriptsJson,
  responseData: output.data,
  workingVars: workingVars,   // mutated in-place for subsequent steps
  environmentId: environmentId,
  workspaceId: workspaceId,
);
_applyPostScripts both updates workingVars for the next iteration of the loop and persists each matched value to the database via upsertVariable, so the extracted token survives even if the run is interrupted.
Variable extraction from one step flows into the next, enabling full authentication + resource workflows. For example: step 1 logs in and captures {{authToken}}; step 2 creates a resource using that token and captures {{resourceId}}; step 3 fetches and asserts on that resource.

Build docs developers (and LLMs) love

Get started for freeTalk to us