Dumpio

A dump is a single JSON value you send to one of Dumpio's servers. Each server is either HTTP (recommended) or TCP (legacy). Both protocols feed into the same normalization, so dumps behave identically afterward. This page describes both protocols and how to talk to them from any language.

HTTP (recommended)

The HTTP server exposes exactly two paths:

Any other method or path returns 404 { "error": "Not found" }.

A single dump

1curl -X POST http://127.0.0.1:21234/dumps \
2  -H 'Content-Type: application/json' \
3  -d '{"message":"User logged in","flag":"green","channel":"auth","user_id":123}'

A batch

Send a JSON array and each element becomes its own dump:

1curl -X POST http://127.0.0.1:21234/dumps \
2  -H 'Content-Type: application/json' \
3  -d '[{"message":"first"},{"message":"second"}]'

Response: 202 {"accepted":2}.

Health check

1curl http://127.0.0.1:21234/health

The /health endpoint is always available on a loopback server and never requires a token.

Error responses

Invalid JSON is not discarded. If the body isn't valid JSON, Dumpio still returns 202 and shows the original text as a red raw dump. So you never lose any data.

TCP (legacy)

The TCP server accepts raw JSON written directly to the socket — no HTTP envelope. It remains for backward compatibility; prefer HTTP for new integrations.

1echo '{"message":"hi","flag":"green"}' | nc localhost 21234

Behavior:

• On connect the server writes a one-line greeting you can ignore: {"type":"welcome","message":"Connected to Dumpio","timestamp":…}.
• Framing is automatic. Dumpio buffers bytes per connection and separates complete JSON values by counting braces (string- and escape-aware), so pretty-printed multi-line JSON and several objects in a row both work. No delimiters are needed.
• Batches: a top-level JSON array is split into one dump per element, just like HTTP.
• Invalid JSON becomes a red raw dump; it isn't discarded.
• The token (if configured) is sent inside the JSON as a token field, because a raw socket has no headers. See Security.
• A connection whose buffer exceeds the maximum size limit is closed.

Reserved envelope fields

When your top-level value is an object, Dumpio reads these fields; everything else is your content.

Client examples

The following examples send to the default HTTP endpoint. Add the token header only if you have a token configured.

curl

1curl -X POST http://127.0.0.1:21234/dumps \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer YOUR_TOKEN' \
4  -d '{"message":"hello","flag":"blue","payload":{"order_id":42}}'

Node.js

1async function dump(data) {
2  await fetch('http://127.0.0.1:21234/dumps', {
3    method: 'POST',
4    headers: { 'Content-Type': 'application/json' },
5    body: JSON.stringify(data)
6  })
7}
8 
9dump({ message: 'User action', flag: 'blue', user_id: 123 })

For Node.js, prefer the official SDK (npm install dumpio-client) — it serializes values into the typed tree, adds flags, and provides middleware for Express/Koa/Fastify. See the Node.js library page.

Python

 1import json, urllib.request
 2 
 3def dump(data):
 4    req = urllib.request.Request(
 5        'http://127.0.0.1:21234/dumps',
 6        data=json.dumps(data).encode(),
 7        headers={'Content-Type': 'application/json'},
 8        method='POST',
 9    )
10    urllib.request.urlopen(req)
11 
12dump({'message': 'User action', 'flag': 'blue', 'user_id': 123})

For Python, prefer the official SDK (pip install dumpio-client) — it serializes values into the typed tree, adds flags, and provides integrations for Django/Flask/FastAPI. See the Python library page.

Go

 1package main
 2 
 3import (
 4    "bytes"
 5    "encoding/json"
 6    "net/http"
 7)
 8 
 9func Dump(data map[string]any) error {
10    body, _ := json.Marshal(data)
11    resp, err := http.Post("http://127.0.0.1:21234/dumps",
12        "application/json", bytes.NewReader(body))
13    if err == nil {
14        resp.Body.Close()
15    }
16    return err
17}

PHP

For PHP, use the official SDK (composer require dumpio/client) — it builds the envelope, flags, labels, timers, and HTML/email previews for you. See the PHP library page.