> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/blocks/response.md).

# response

The Response block is the final step in your workflow that formats and returns data to whoever called your workflow. It's like the "return" statement for your entire workflow—it packages up results and sends them back.

{% hint style="info" %}
Response blocks are terminal blocks - they end the workflow execution and cannot connect to other blocks.
{% endhint %}

### When You Need Response Blocks

**API Endpoints**: When your workflow is called via API, Response blocks format the return data\
**Webhooks**: Return confirmation or data back to the calling system\
**Testing**: See formatted results when testing your workflow\
**Data Export**: Structure data for external systems or reports

### Two Ways to Build Responses

{% tabs %}
{% tab title="Builder Mode (Recommended)" %}
Visual interface for building response structure:

* Drag and drop fields
* Reference workflow variables easily
* Visual preview of response structure
  {% endtab %}

{% tab title="Editor Mode (Advanced)" %}
Write JSON directly:

* Full control over response format
* Support for complex nested structures
* Use `<variable.name>` syntax for dynamic values
  {% endtab %}
  {% endtabs %}

### 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

Set the HTTP status code for the response. Common status codes include:

{% tabs %}
{% tab title="Success (2xx)" %}

* **200**: OK - Standard success response
* **201**: Created - Resource successfully created
* **204**: No Content - Success with no response body
  {% endtab %}

{% tab title="Client Error (4xx)" %}

* **400**: Bad Request - Invalid request parameters
* **401**: Unauthorized - Authentication required
* **404**: Not Found - Resource doesn't exist
* **422**: Unprocessable Entity - Validation errors
  {% endtab %}

{% tab title="Server Error (5xx)" %}

* **500**: Internal Server Error - Server-side error
* **502**: Bad Gateway - External service error
* **503**: Service Unavailable - Service temporarily down
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
Default status code is 200 if not specified.
{% endhint %}

#### 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              |

### Inputs and Outputs

{% tabs %}
{% tab title="Inputs" %}

* **data** (JSON, optional): The JSON data to send in the response body
* **status** (number, optional): HTTP status code (default: 200)
* **headers** (JSON, optional): Additional response headers
  {% endtab %}

{% tab title="Outputs" %}

* **data**: The response body data
* **status**: HTTP status code
* **headers**: Response headers
  {% endtab %}
  {% endtabs %}

### 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"
}
```

{% hint style="warning" %}
Variable names are case-sensitive and must match exactly with the variables available in your workflow.
{% endhint %}

### Example Usage

Here's an example of how a Response block might be configured for a user search API:

```yaml
data: |
  {
    "success": true,
    "data": {
      "users": "<variable.searchResults>",
      "pagination": {
        "page": "<variable.currentPage>",
        "limit": "<variable.pageSize>",
        "total": "<variable.totalUsers>"
      }
    },
    "query": {
      "searchTerm": "<variable.searchTerm>",
      "filters": "<variable.appliedFilters>"
    },
    "timestamp": "<variable.timestamp>"
  }
status: 200
headers:
  - key: X-Total-Count
    value: <variable.totalUsers>
  - key: Cache-Control
    value: public, max-age=300
```

### 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.aitech.io/agentforge/blocks/response.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.