Surge API Docs

Surge is a browser-based bulk API orchestrator. You upload a spreadsheet of data, design one (or many) API request templates, and Surge fires them all — in parallel or sequentially — row by row. Think of it as “mail merge” for API calls.

It’s built for repetitive tasks: bulk-creating customers, verifying records, migrating data, or smoke-testing an endpoint across thousands of inputs.

Drag & drop (or click to browse) a .csv, .xlsx, or .xls file into the Data Source panel on the left.

Surge will parse the file automatically. Each column header becomes a variable you can reference later.

name,email,phone
Alice,alice@example.com,+84 912 345 678
Bob,bob@acme.co,+84 987 654 321
Charlie,charlie@test.org,+84 901 234 567

After uploading, the panel shows a preview table. You can change the data type for each column (string, number, boolean) — this controls how the value is serialised when it gets injected into request bodies.

In the Request Designer panel, configure the API call you want to make for every row of your spreadsheet.

Method & URL

Pick a method (GET, POST, PUT, PATCH, DELETE, QUERY) and enter the endpoint URL. Use {{column_name}} placeholders to inject values from your spreadsheet.

https://api.example.com/customers/{{email}}

Headers

Add headers like Authorization or Content-Type. If you don’t set Content-Type, Surge auto-adds application/json when a JSON body is detected.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Query Params

You can add query parameters as key-value pairs. They support {{variable}} interpolation too.

Body (JSON)

Write your JSON body in the built-in Monaco editor. Use the same {{column_name}} syntax.

{
  "name": "{{name}}",
  "email": "{{email}}",
  "phone": "{{phone}}",
  "source": "bulk_import"
}

When the column type is set to number or boolean, the value is injected without quotes so the resulting JSON is valid.

cURL Import & Export

Already have a cURL command? Paste it into the URL field — Surge auto-parses method, URL, headers, and body. You can also copy the current template out as cURL to share with colleagues.

curl --request POST \
  --url 'https://api.example.com/customers' \
  --header 'Authorization: Bearer token123' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "{{name}}",
    "email": "{{email}}"
  }'

Need to call more than one endpoint per row? Click + Add Step in the left sidebar of the Request Designer.

Steps execute sequentially for each row. For example:

1. Step 1 — Create a customer via POST /customers
2. Step 2 — Verify the customer via GET /customers/{{email}}

Drag and drop steps to reorder them. If any step fails, the chain is marked as an error but continues to subsequent steps so you still get partial data.

The Execution Engine panel lets you configure:

• Concurrency Limit — how many rows are processed in parallel (1–50). Setting it to 1 means purely sequential.

Test Row 1

Before blasting all rows, click Test Row 1 to execute only the first row as a dry run. Check the result, inspect the response body, and make sure everything is correct before committing.

Run Engine

Click Run Engine to execute all rows. A progress bar shows how far along you are. You can Stop Execution at any time — already-completed rows are kept, pending rows are cancelled.

After execution, scroll down to the Results table. Each row shows status, status code, response time, and the raw response body.

Column Mapping

Need to pull specific values out of the response? Use column mappings. For each column you define:

• Name — column header in the export
• Source — one of: Variable, Request Body, Request Param, Response, Status, Error
• Path — dot-notation path into the JSON, e.g. data.customer.id

Response JSON:
{
  "data": {
    "customer": {
      "id": "cust_abc123",
      "status": "active"
    }
  }
}

Column Mapping:
  Name: "Customer ID"   → Source: Response  → Path: data.customer.id
  Name: "Status"        → Source: Response  → Path: data.customer.status

Export to Excel

Click the Export button in the results table header to download an .xlsx file with all mapped columns.

Your entire Surge workspace — uploaded data, request templates, and results — persists in localStorage. You can also export it as a .json file and import it later or share it with a colleague.

• Export — downloads a surge-workspace-YYYY-MM-DD.json file
• Import — opens a file picker, loads the workspace JSON
• Clear — nukes everything (asks for confirmation first)