API Sequences

API Sequences help you define and test multi-step API interactions in one place. Use them to generate request chains quickly, review each run in detail, and fix failures faster with AI Doctor.

01When to use API sequences

Use API Sequences when you need to validate an API flow that spans multiple requests, shared data, or step-by-step assertions. They are especially useful when you want to generate a starting sequence from a prompt or from an existing workflow run, then refine it through repeated runs.

Common use cases include:

• Testing login, checkout, or other multi-request journeys
• Reproducing API issues from a failed or flaky workflow run
• Verifying response data and assertions at each step
• Iterating on a sequence with AI-assisted fixes or improvements

02Core concepts

API Sequences combine sequence configuration, run history, detailed result inspection, and AI-assisted troubleshooting. Together, these views help you move from generation to verification without leaving the sequence workflow.

Sequence configuration

Sequence configuration defines the requests, ordering, inputs, and validation behavior for a sequence. Use it to control how the sequence runs and what success looks like for each step.

When you review configuration, focus on:

• The ordered list of API requests in the sequence
• Any values or request details that must be updated before a run
• Validation logic that determines whether a step passes, warns, or fails
• The overall flow of dependent steps and shared context

Run history and results

Every sequence keeps a run history so you can compare attempts, open prior results, and understand how changes affect outcomes over time. Run summaries and result drawers make it easier to inspect what happened without digging through raw logs.

Use run history to:

• Reopen recent runs and compare outcomes
• Spot repeated failures or warnings across attempts
• Review assertion summaries and step-level results
• Return to an AI Doctor analysis after a rerun
• Retry after making manual or AI-generated fixes
• Correlate sequence traffic with your own backend traces when observability is enabled

When observability trace headers are enabled for API sequence traffic, Canary adds trace context to sequence requests so you can line up a run with the matching requests or spans in your own observability tools. API sequence runs now carry those headers more consistently, which makes request-to-run correlation more reliable when you inspect backend behavior.

Manage this behavior in your organization's observability settings. Organization admins can configure API sequence trace headers separately from browser-driven request trace headers.

AI Doctor

AI Doctor is available throughout the API Sequence workflow. Open it from a run when you need help with a failed sequence, or use it proactively from the sequence editor when you want suggestions before you apply changes.

AI Doctor supports two common workflows:

• Diagnose failed sequences to identify likely causes and recommend targeted changes
• Improve weak or incomplete sequences to make them clearer, more resilient, or better validated

Before Canary applies changes, review the confirmation dialog, add optional guidance if needed, and then continue with the fix or improvement.

03Creating and generating sequences

You can create API Sequences by starting from a prompt or by generating from an existing workflow run. If the sequence does not yet have a successful run, Canary can generate an API-only sequence directly from your prompt. Generation stays active if you navigate away from the page or refresh, and the sequence reconnects when you return.

Generate from prompt

Use prompt-based generation when you know the API journey you want to test but do not want to build each step manually.

1. Open API Sequences.
2. Click Generate.
3. Enter a prompt that describes the API flow you want to create.
4. Start generation and review the steps as they stream in.
5. Navigate away, switch pages, or refresh if needed.
6. Return to the sequence to reconnect automatically and keep following progress.
7. Review the generated sequence and update any request details before running it.

Write prompts that describe the goal, the key requests, and the expected outcome. The more specific you are about the flow, the easier it is to get a useful first draft.

If you leave during generation, expect the sequence to keep generating in the background. When you return, Canary reconnects to the in-progress generation and resumes live updates instead of starting over.

Generate from workflow run

Use generation from a workflow run when you want to turn a real execution path into an API Sequence. This is useful for debugging a failed run or capturing a known-good path for regression coverage.

1. Open the workflow run you want to use as a source.
2. Start sequence generation from that run.
3. Let the sequence populate from the captured request flow.
4. Leave the page or refresh if needed.
5. Reopen the sequence to reconnect automatically and continue reviewing generation.
6. Review the generated steps and remove anything you do not want to keep.
7. Save the sequence and run it independently.

This workflow gives you a faster starting point when you already have a run that represents the behavior you want to inspect or preserve.

The same durable progress experience applies here. If generation is still in progress when you switch pages or refresh, reopen the sequence to reconnect to the live stream and continue from the current state.

API-only generation

Use API-only generation when you start from a prompt and no successful run exists yet. This path lets you generate a sequence directly from the prompt instead of waiting for a prior run to succeed.

Open API Sequences, enter your prompt, and start generation. Canary creates the initial request chain from your description alone, so you can review and refine the sequence before the first run.

Use this path when you want to:

• Draft a new sequence before you have a captured run
• Explore an API flow from a written description
• Create a starting point for validation and troubleshooting

After generation completes, review each step carefully. Confirm request details, fill in any missing values, and then run the sequence to validate the flow.

04Running and reviewing sequences

After you create a sequence, run it to verify each step, inspect responses, and review validation results. The run experience is designed to help you move quickly between summaries and step-level detail.

How API sequences execute

API Sequences run steps in order and carry forward the state created by earlier requests. This lets later steps reuse mapped values, cookies set during earlier requests, and browser-derived authentication handed off from a saved session when the flow depends on an authenticated context.

Use this behavior for flows such as sign-in, checkout, account management, and SPA-backed API calls where a browser session captures the auth you want to reuse.

For example, you can:

• Sign in in the first step and call protected endpoints in later steps
• Start a cart or checkout flow and continue it across multiple requests
• Validate APIs that rely on server-managed session cookies instead of only explicit tokens
• Reuse tokens captured in a browser session instead of manually rebuilding Authorization headers

When you run a sequence with browser-backed execution or Auth Handoff, Canary forwards browser-derived auth into the request context before the sequence runs. This includes supported credentials stored in localStorage, IndexedDB, and cookies, so downstream requests can behave more like the authenticated browser flow they came from.

Use this setup for modern single-page apps and token-based APIs when login state lives in the browser instead of being created by the first API step in the sequence.

Understanding run statuses

Run statuses help you understand the overall outcome at a glance. Review both the sequence-level status and the step-level indicators before deciding what to fix.

Status	What it means
Passed	The sequence completed and validations passed.
Warning	The sequence completed, but one or more validations returned warnings.
Failed	One or more steps or validations failed and need attention.
In progress	The sequence is still running or results are still updating.

Warnings are useful when you want to capture issues without treating them as hard failures. Use them to monitor conditions that matter but should not always block the run.

Publish readiness after a run

After a successful run, check whether Canary surfaces Publish right away. For API-only sequences, Canary now recalculates publish readiness after the run finishes, so you can promote the sequence immediately when it has publishable changes.

Use this updated behavior to confirm whether the latest generated or edited state is ready to move forward:

• If Publish appears after the run, the sequence has publishable changes and is ready to promote.
• If Publish does not appear, review whether the latest run produced any changes worth publishing or rerun after additional edits.
• If you recently generated or updated the sequence, rely on the post-run state instead of refreshing the page to confirm readiness.

This helps you move directly from validation to promotion without interrupting your review flow.

Inspecting request and response details

Open the result drawer to inspect request and response details for each step. Use this view to confirm request inputs, review returned data, and understand where the sequence diverges from your expectation.

Focus on:

• Which request ran at each step
• What the response returned
• Whether the request chain used the expected values
• Whether cookies, tokens, or other authenticated state from earlier steps or browser auth handoff were available where you expected them
• Whether observability trace headers were present when you need to correlate the run with your backend logs or traces
• Where the first unexpected result appeared

Use request inspection when you need to debug across systems. If observability is enabled for API sequence traffic, compare the request details in Canary with the matching trace or log entries in your backend tools to confirm the exact path a run took.

When trace headers are enabled, expect API sequence requests to participate in your existing trace correlation flow. Use the sequence run details in Canary as the starting point, then search your backend logs, traces, or spans for the matching request activity. Because Canary now applies those headers more consistently during API sequence runs, the correlation is more dependable across the full sequence.

If you do not see matching trace data, confirm that an organization admin enabled trace headers for API sequence traffic in Observability settings. This setting is managed at the organization level and is separate from browser-driven request trace-header controls.

Validation results and failures

Validation results show whether each step passed, warned, or failed. Use these results to quickly isolate the exact condition that broke the run.

When a run fails, review:

1. The overall run summary
2. Any step-level warning or failure indicators
3. The first failed validation
4. The related request and response details
5. Whether the issue comes from test logic, request data, authentication or session state, or an upstream dependency

This layered view helps you pinpoint the issue before you make changes or open AI Doctor.

05Fixing and improving sequences with AI Doctor

Use AI Doctor when you want guided help instead of manually tracing every issue. Open it from a failed run when you need a repair path, or open it before you apply changes when you want suggestions on how to improve the sequence.

Diagnose failed runs

Open AI Doctor from a failed run to get a diagnosis of what likely went wrong. Start here when the cause is not obvious from the run summary alone.

AI Doctor can help you:

• Identify likely failure points in the sequence
• Understand which step or validation needs attention
• Generate a targeted fix based on the run details
• Add guidance if you want to steer the fix toward a specific outcome

When you ask Canary to fix a sequence, review the suggested changes, confirm the action, and then apply them if they match your intent.

Improve successful runs

Open AI Doctor from a successful or warning-level run when you want to strengthen the sequence instead of repairing it. This is useful when the sequence passes but still needs cleaner structure, better validation, or more resilient steps.

Use this path to:

• Tighten validation coverage
• Clarify request flow and step intent
• Improve sequence reliability
• Refine a generated sequence before broader reuse

When you ask Canary to improve a sequence, use the same confirmation flow to review the action and include optional guidance if needed.

Apply fixes and retry

After AI Doctor suggests changes, review them before you apply them. Then rerun the sequence to confirm the update resolves the issue or improves the result.

1. Open AI Doctor from the run or sequence.
2. Choose whether to diagnose a failure or improve the sequence.
3. Review the suggested changes and confirmation dialog.
4. Add optional guidance if needed.
5. Apply the proposed changes.
6. Run the sequence again.
7. Compare the new run against the previous result in run history.

Use run history to follow the full loop from original run, to Doctor analysis, to rerun. This makes it easier to confirm whether the applied changes actually improved the sequence.

If the rerun succeeds, check for Publish before you leave the sequence. Canary recalculates stale or generated state after runs, so the sequence reflects its latest publish readiness without requiring a manual refresh.

06Configuration

Use sequence configuration to pass data from one step into another. You can now map extracted values from either a request body or a response body, depending on where the data first becomes available.

API sequence observability behavior is also configured at the organization level. If you want sequence traffic to include trace headers for correlation in your logging or tracing tools, ask an organization admin to enable trace headers for API sequence traffic in Observability settings.

Mapping sources

Choose the mapping source based on what you need to reuse downstream.

Mapping source	Use it when	Example
Request body	You want to reuse a value you already send upstream.	Reuse a created email address or account ID from a setup request in a later step.
Response body	You want to reuse a value returned by the API.	Reuse a generated user ID, token, or order number returned by an earlier response.

Use request body mapping when the upstream request contains the exact value you want to carry forward. Use response body mapping when the API creates, transforms, or returns the value only after the request runs.

Configure mapped values

1. Open your sequence and select the upstream step.
2. Identify the value you want to reuse in a downstream step.
3. Choose whether to extract it from the request body or the response body.
4. Save the mapped value.
5. Reference that mapped value in the downstream step where you need it.
6. Run the sequence and verify the downstream step receives the expected value.

When you troubleshoot a broken chain, first confirm you picked the correct source. If the value is entered manually in the upstream request, map from the request body. If the value appears only after the API responds, map from the response body.

Validation and variable references

Canary now catches invalid $var references earlier while you configure a sequence. This helps you fix missing or incorrect upstream references before you run the full sequence.

If a variable reference is flagged:

• Confirm the referenced value exists in an earlier step
• Confirm the reference name matches the mapped value exactly
• Confirm the downstream step points to a valid upstream value
• Update the mapping source if the value comes from the request body instead of the response body, or the reverse

Use early validation to correct sequence wiring as you edit instead of waiting for a run to fail.

07Options

Use these options when you decide how to wire data between steps.

Option	Description
Map from request body	Extract a value from the body you send in an upstream request.
Map from response body	Extract a value from the body returned by an upstream response.
$var reference	Reuse a mapped value in a later step. Invalid references are now flagged earlier during configuration.

08Authentication and credentials

Use API Sequences to test authenticated flows that span multiple requests. When an earlier step sets cookies, later steps in the same sequence automatically carry that session state forward.

For browser-based authentication, use Auth Handoff in credentials to forward saved browser auth into the sequence before the first request runs. This lets the sequence reuse supported tokens and session data captured from browser sessions, including values stored in localStorage, IndexedDB, and cookies.

Use Auth Handoff when you need to:

• Test a single-page app that stores auth in the browser instead of establishing it in the first API step
• Reuse a saved login session for downstream API testing
• Validate token-based APIs without manually recreating headers or refresh flows
• Start a sequence from an already authenticated browser context

1. Open the credential setup for the sequence.
2. Go to the Auth Handoff area.
3. Select the browser-backed credential or saved session you want to reuse.
4. Save the credential setup.
5. Run the sequence and confirm protected requests succeed with the handed-off auth.

At the request level, choose the option to use auth from the browser session when you want a request to inherit that browser-derived authentication context.

Use browser-derived auth for SPA and token-based APIs when the browser is already the source of truth for login state. Use regular step-to-step session carry-forward when the sequence itself creates the session by signing in or setting cookies in an earlier request.

If a later step returns an authentication or authorization error, confirm that you selected the correct browser session, that the saved session is still valid, and that the request is configured to use the handed-off auth where needed.

09Best practices

• Start with generation, then tighten the sequence before relying on it for repeated runs.
• Run the sequence after generated or major edited changes, then look for Publish immediately after a successful run.
• Use the post-run state to judge promotion readiness instead of refreshing the page.
• Use run history to compare attempts instead of troubleshooting only from the latest result.
• Review the first warning or failure before editing later steps.
• Use warning-level validations when you want visibility without blocking the entire run.
• Open AI Doctor early when a failure is unclear or when a passing sequence still needs improvement.
• Generate from a workflow run when you want the fastest path from observed behavior to a reusable API Sequence.
• Use a sequence when your flow depends on shared session state, not just individual independent requests.
• Sign in or establish session state early in the sequence so later steps can reuse carried-forward cookies.
• Use Auth Handoff when your app stores login state in localStorage, IndexedDB, or browser cookies instead of creating it inside the sequence.
• Prefer browser-derived auth for SPA and token-based APIs when you want the sequence to mirror a real signed-in browser session.
• When you debug authenticated failures, check the earliest step that should create the session or confirm the handed-off browser auth is still valid before changing downstream requests.
• For browser-backed execution, use API Sequences for setup calls that send JSON payloads or take longer to complete, because request handling is now more reliable for those cases.
• For API-only execution, rerun the full sequence when you need to confirm session-dependent requests behave consistently end to end.
• Map from the request body when you need to reuse a value you already control in the upstream step.
• Map from the response body when you need a value the API returns after execution.
• Keep mapped value names consistent so $var references stay easy to recognize and validate.
• Fix invalid $var references as soon as Canary flags them to avoid downstream run failures.

10Related

• Workflows
• Workflow runs
• Observability settings
• Seed Data
• Tasks