---
title: "Connector Proxy API Examples — Spiff Arena 0.1 documentation"
description: "This page provides sample requests and responses for connector proxy implementations."
source_url: https://spiff.works/docs/spiff-arena/explanation/dev/connector_proxy_examples.html
---

☰ Menu

# Connector Proxy API Examples[](#connector-proxy-api-examples "Link to this heading")

This page provides sample requests and responses for connector proxy implementations.

## [Request Examples](#id1)[](#request-examples "Link to this heading")

### [List Available Commands](#id2)[](#list-available-commands "Link to this heading")

```
curl -s http://localhost:8200/v1/commands | jq
```

### [Execute a GET Request](#id3)[](#execute-a-get-request "Link to this heading")

**Endpoint:**

```
POST /v1/do/http/GetRequest
```

**Request Payload:**

```
{
  "url": "https://api.example.com/items",
  "headers": { "Accept": "application/json" },
  "params": { "limit": 10 }
}
```

### [Execute a POST Request](#id4)[](#execute-a-post-request "Link to this heading")

**Endpoint:**

```
POST /v1/do/http/PostRequest
```

**Request Payload:**

```
{
  "url": "https://api.example.com/items",
  "headers": { "Content-Type": "application/json" },
  "data": { "name": "example" }
}
```

`data` is sent as JSON by default. To send a form-encoded request body, set `body_format` to `form`:

```
{
  "url": "https://auth.example.com/realms/demo/protocol/openid-connect/token",
  "headers": { "Content-Type": "application/x-www-form-urlencoded" },
  "body_format": "form",
  "data": {
    "grant_type": "password",
    "client_id": "admin-cli",
    "username": "admin",
    "password": "secret"
  }
}
```

### [Execute a DELETE Request](#id5)[](#execute-a-delete-request "Link to this heading")

**Endpoint:**

```
POST /v1/do/http/DeleteRequest
```

**Request Payload:**

```
{
  "url": "https://api.example.com/items/123",
  "headers": { "Authorization": "Bearer token" }
}
```

### [Execute a PUT Request](#id6)[](#execute-a-put-request "Link to this heading")

**Endpoint:**

```
POST /v1/do/http/PutRequest
```

**Request Payload:**

```
{
  "url": "https://api.example.com/items/123",
  "headers": { "Content-Type": "application/json" },
  "data": { "name": "updated-example", "status": "active" }
}
```

### [Execute a PATCH Request](#id7)[](#execute-a-patch-request "Link to this heading")

**Endpoint:**

```
POST /v1/do/http/PatchRequest
```

**Request Payload:**

```
{
  "url": "https://api.example.com/items/123",
  "headers": { "Content-Type": "application/json" },
  "data": { "status": "active" }
}
```

### [Execute a HEAD Request](#id8)[](#execute-a-head-request "Link to this heading")

**Endpoint:**

```
POST /v1/do/http/HeadRequest
```

**Request Payload:**

```
{
  "url": "https://api.example.com/items/123",
  "headers": { "Accept": "application/json" }
}
```

### [Execute with Basic Authentication](#id9)[](#execute-with-basic-authentication "Link to this heading")

```
{
  "url": "https://api.example.com/secure",
  "basic_auth_username": "user",
  "basic_auth_password": "pass"
}
```

---

## [Response Examples](#id10)[](#response-examples "Link to this heading")

### [Standard Response Envelope](#id11)[](#standard-response-envelope "Link to this heading")

All commands return a response envelope with this structure:

```
{
  "command_response": {
    "body": {},
    "mimetype": "application/json",
    "http_status": 200
  },
  "command_response_version": 2,
  "error": null,
  "spiff__logs": []
}
```

### [Successful JSON Response](#id12)[](#successful-json-response "Link to this heading")

When the upstream service returns JSON with a `200 OK` status:

```
{
  "command_response": {
    "body": {
      "id": 123,
      "name": "example item",
      "status": "active"
    },
    "mimetype": "application/json",
    "http_status": 200
  },
  "command_response_version": 2,
  "error": null,
  "spiff__logs": []
}
```

### [Non-JSON Response (Raw Text)](#id13)[](#non-json-response-raw-text "Link to this heading")

When the upstream service returns non-JSON content:

```
{
  "command_response": {
    "body": {
      "raw_response": "Plain text response from the service"
    },
    "mimetype": "application/json",
    "http_status": 200
  },
  "command_response_version": 2,
  "error": null,
  "spiff__logs": []
}
```

### [Error Response](#id14)[](#error-response "Link to this heading")

When an error occurs:

```
{
  "command_response": {
    "body": {},
    "mimetype": "application/json",
    "http_status": 500
  },
  "command_response_version": 2,
  "error": {
    "message": "Connection timeout",
    "error_code": "TIMEOUT_ERROR"
  },
  "spiff__logs": [
    "Attempted connection to https://api.example.com/items",
    "Request timed out after 30 seconds"
  ]
}
```

### [HTTP 202 Accepted Response (Long-Running Tasks)](#id15)[](#http-202-accepted-response-long-running-tasks "Link to this heading")

When a service task initiates a long-running operation:

```
{
  "command_response": {
    "body": {
      "task_id": "abc-123",
      "status": "processing"
    },
    "mimetype": "application/json",
    "http_status": 202
  },
  "command_response_version": 2,
  "error": null,
  "spiff__logs": []
}
```

> **Note:** When a connector proxy returns a `202 (Accepted)` response, SpiffWorkflow will leave the service task in a **WAITING** state. See [Long-Running Service Tasks](../../how_to_guides/building_diagrams/long_running_service_tasks.html) for more details.

---

## [Response Parsing Behavior](#id16)[](#response-parsing-behavior "Link to this heading")

- If the upstream response `Content-Type` includes `application/json`, the proxy parses JSON into `command_response.body`
- Otherwise, the raw text is wrapped in:

  ```
  { "raw_response": "<text>" }
  ```
- The `mimetype` field in the async-http example is set to `"application/json"` for all responses, including raw text responses

---

## [Using Callback URLs (Long-Running Tasks)](#id17)[](#using-callback-urls-long-running-tasks "Link to this heading")

When SpiffWorkflow invokes a service task, it automatically includes a `spiff__callback_url` parameter. If your service needs to process the request asynchronously:

1. **Return a 202 response** to indicate the task is accepted but not yet complete
2. **Call the callback URL later** when processing is done

### [Callback Request Format](#id18)[](#callback-request-format "Link to this heading")

When your service is ready to complete the task, send a **PUT** request to the `spiff__callback_url` using the connector proxy response envelope format:

> **Important:** The `command_response.body` field is **required** in all callback requests. Omitting this structure will result in an `invalid_callback_body` error from SpiffWorkflow.

```
PUT <spiff__callback_url>
Content-Type: application/json

{
  "command_response": {
    "body": {
      "order_id": "12345",
      "status": "complete",
      "details": "Processing finished successfully"
    },
    "mimetype": "application/json",
    "http_status": 200
  },
  "command_response_version": 2,
  "error": null,
  "spiff__logs": []
}
```

The `command_response.body` field contains your actual result data. SpiffWorkflow extracts this value and stores it in the service task’s configured result variable.

See [Long-Running Service Tasks](../../how_to_guides/building_diagrams/long_running_service_tasks.html) for complete documentation.