sim/apps/docs/content/docs/en/blocks/response.mdx

---
title: Response
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Image } from '@/components/ui/image'
import { FAQ } from '@/components/ui/faq'

The Response block formats and sends structured HTTP responses back to API callers. Use it to return workflow results with proper status codes and headers.

<div className="flex justify-center">
  <Image
    src="/static/blocks/response.png"
    alt="Response Block Configuration"
    width={500}
    height={400}
    className="my-6"
  />
</div>

<Callout type="info">
  Response blocks are exit points — when a Response block executes, it ends the workflow and sends the HTTP response immediately. Multiple Response blocks can be placed on different branches (e.g. after a Router or Condition), but only the first one to execute determines the API response.
</Callout>

## Configuration Options

### Response Data

The response data is the main content that will be sent back to the API caller. This should be formatted as JSON and can include:

- Static values
- Dynamic references to workflow variables using the `<variable.name>` syntax
- Nested objects and arrays
- Any valid JSON structure

### Status Code

A free-text input field where you can enter any valid HTTP status code (the default placeholder is 200). Common examples include:

- **200**: OK - Standard success response
- **201**: Created - Resource successfully created
- **400**: Bad Request - Invalid request parameters
- **404**: Not Found - Resource doesn't exist
- **500**: Internal Server Error - Server-side error

Any valid HTTP status code can be entered directly into the field.

### Response Headers

Configure additional HTTP headers to include in the response.

Headers are configured as key-value pairs:

| Key | Value |
|-----|-------|
| Content-Type | application/json |
| Cache-Control | no-cache |
| X-API-Version | 1.0 |

## Example Use Cases

**API Endpoint Response** - Return structured data from a search API
```
Agent (Search) → Function (Format & Paginate) → Response (200, JSON)
```

**Webhook Confirmation** - Acknowledge webhook receipt and processing
```
Webhook Trigger → Function (Process) → Response (200, Confirmation)
```

**Error Response Handling** - Return appropriate error responses
```
Condition (Error Detected) → Router → Response (400/500, Error Details)
```

## Outputs

Response blocks are exit points — when one executes, no further blocks run. The block defines outputs (`data`, `status`, `headers`) which are used to construct the HTTP response sent back to the API caller.

<Callout type="warning">
  If a Response block is placed on a parallel branch, there are no guarantees about whether other parallel blocks will run or not. Execution order across parallel branches is non-deterministic, so a parallel block may execute before or after the Response block on any given run. Avoid placing Response blocks in parallel with blocks that have important side effects.
</Callout>

## Variable References

Use the `<variable.name>` syntax to dynamically insert workflow variables into your response:

```json
{
  "user": {
    "id": "<variable.userId>",
    "name": "<variable.userName>",
    "email": "<variable.userEmail>"
  },
  "query": "<variable.searchQuery>",
  "results": "<variable.searchResults>",
  "totalFound": "<variable.resultCount>",
  "processingTime": "<variable.executionTime>ms"
}
```

<Callout type="warning">
  Variable names are case-sensitive and must match exactly with the variables available in your workflow.
</Callout>

## Best Practices

- **Use meaningful status codes**: Choose appropriate HTTP status codes that accurately reflect the outcome of the workflow
- **Structure your responses consistently**: Maintain a consistent JSON structure across all your API endpoints for better developer experience
- **Include relevant metadata**: Add timestamps and version information to help with debugging and monitoring
- **Handle errors gracefully**: Use conditional logic in your workflow to set appropriate error responses with descriptive messages
- **Validate variable references**: Ensure all referenced variables exist and contain the expected data types before the Response block executes

<FAQ items={[
  { question: "Can I have multiple Response blocks in a workflow?", answer: "Yes. You can place multiple Response blocks on different branches (e.g. after a Router or Condition block). The first Response block to execute determines the API response and ends the workflow. This is useful for returning different responses based on conditions — for example, a 200 on the success branch and a 500 on the error branch." },
  { question: "What triggers require a Response block?", answer: "The Response block is designed for use with the API Trigger. When your workflow is invoked via the API, the Response block sends the structured HTTP response back to the caller. Other trigger types (like webhooks or schedules) do not require a Response block." },
  { question: "What is the difference between Builder and Editor mode?", answer: "Builder mode provides a visual interface for constructing your response structure with fields and types. Editor mode gives you a raw JSON code editor where you can write the response body directly. Builder mode is recommended for most use cases." },
  { question: "What is the default status code?", answer: "If you do not specify a status code, the Response block defaults to 200 (OK). You can set any valid HTTP status code including error codes like 400, 404, or 500." },
  { question: "Can the Response block connect to downstream blocks?", answer: "No. Response blocks are exit points — they end workflow execution and send the HTTP response. No further blocks can execute after a Response block." },
]} />