HTTP

The io.b3os/http pack: 8 actions with call snippets, fixture outputs, connection setup and error codes, generated from version 1.0.0.

io.b3os/http 1.0.0 · http, developer-tools, webhooks · MIT

Plain HTTP requests to public URLs: GET and HEAD, and POST, PUT, PATCH or DELETE with a JSON, form or text body. For public APIs without a pack and for URLs that carry their own authorization, such as webhook URLs and presigned links. No credentials are ever attached; private and loopback addresses are refused. Prefer a provider pack when one exists: it has typed inputs and outputs.

Every call's result carries upstream_status and timing: validate_ms, inject_ms, render_ms, upstream_ms, map_ms and total_ms. upstream is the service's time; the others are B3OS's own (call actions). The snippets below show no timing values, because a fixture records none.

Connection

No credential: a keyless public API. Calls name no connection.

Hosts it reaches: *.

Actions

Action	Effect	MCP tool	Title
`get`	read	`http__get`	GET a URL
`head`	read	`http__head`	HEAD a URL
`post-json`	irreversible	`http__post-json`	POST JSON
`post-form`	irreversible	`http__post-form`	POST form
`post-text`	irreversible	`http__post-text`	POST text
`put-json`	irreversible	`http__put-json`	PUT JSON
`patch-json`	irreversible	`http__patch-json`	PATCH JSON
`delete`	irreversible	`http__delete`	DELETE a URL

`get`

GET a URL. Fetch a URL with GET and return the status, content type, Location and ETag headers, and the body (parsed JSON when the response is JSON, otherwise text). Non-2xx statuses fail with an error code unless fail_on_error_status is false.

Ref io.b3os/http/get@1.0.0 · effect read · no connection · MCP tool http__get

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/get@1",      "input": {"url": "https://httpbin.org/json"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/get@1",  input: { url: "https://httpbin.org/json" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/get@1",    "input": {"url": "https://httpbin.org/json"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__get",    "arguments": {"url": "https://httpbin.org/json"}  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__get with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: GET a URL (response recorded 2026-10-26). From the bundle's fixtures/get-json.json, not a live call.

json
{  "status": 200,  "content_type": "application/json",  "location": null,  "etag": null,  "body": {    "slideshow": {      "author": "Yours Truly",      "date": "date of publication",      "slides": [        {"title": "Wake up to WonderWidgets!", "type": "all"},        {          "items": [            "Why <em>WonderWidgets</em> are great",            "Who <em>buys</em> WonderWidgets"          ],          "title": "Overview",          "type": "all"        }      ],      "title": "Sample Slide Show"    }  }}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

`head`

HEAD a URL. Check a URL without downloading it: status, content type, content length, ETag, Last-Modified and Location (for redirects).

Ref io.b3os/http/head@1.0.0 · effect read · no connection · MCP tool http__head

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/head@1",      "input": {"url": "https://httpbin.org/robots.txt"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/head@1",  input: { url: "https://httpbin.org/robots.txt" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/head@1",    "input": {"url": "https://httpbin.org/robots.txt"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__head",    "arguments": {"url": "https://httpbin.org/robots.txt"}  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__head with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: HEAD a URL (response recorded 2026-10-26). From the bundle's fixtures/head.json, not a live call.

json
{  "status": 200,  "content_type": "text/plain",  "content_length": "30",  "etag": null,  "last_modified": null,  "location": null}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

`post-json`

POST JSON. POST a JSON body to a URL (a webhook, an API endpoint without a pack) and return the status and the response body. Not idempotent: retrying may repeat the effect.

Ref io.b3os/http/post-json@1.0.0 · effect irreversible · no connection · MCP tool http__post-json

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/post-json@1",      "input": {        "url": "https://httpbin.org/anything/hooks/deploy",        "body": {"event": "deploy", "version": "2.4.1", "ok": true}      }    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/post-json@1",  input: {    url: "https://httpbin.org/anything/hooks/deploy",    body: { event: "deploy", version: "2.4.1", ok: true },  },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/post-json@1",    "input": {        "url": "https://httpbin.org/anything/hooks/deploy",        "body": {"event": "deploy", "version": "2.4.1", "ok": True},    },}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__post-json",    "arguments": {      "url": "https://httpbin.org/anything/hooks/deploy",      "body": {"event": "deploy", "version": "2.4.1", "ok": true}    }  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__post-json with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: POST JSON (response recorded 2026-10-26). From the bundle's fixtures/post-json.json, not a live call.

json
{  "status": 200,  "content_type": "application/json",  "location": null,  "etag": null,  "body": {    "args": {},    "data": "{\"event\":\"deploy\",\"version\":\"2.4.1\",\"ok\":true}",    "files": {},    "form": {},    "headers": {      "Accept": "application/json, text/*;q=0.9, */*;q=0.8",      "Accept-Encoding": "br, gzip, deflate",      "Accept-Language": "*",      "Content-Length": "46",      "Content-Type": "application/json",      "Host": "httpbin.org",      "Sec-Fetch-Mode": "cors",      "User-Agent": "b3os-actions/1 (+https://beta.b3os.org)"    },    "json": {"event": "deploy", "ok": true, "version": "2.4.1"},    "method": "POST",    "url": "https://httpbin.org/anything/hooks/deploy"  }}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

`post-form`

POST form. POST form fields (application/x-www-form-urlencoded) to a URL and return the status and the response body. Not idempotent.

Ref io.b3os/http/post-form@1.0.0 · effect irreversible · no connection · MCP tool http__post-form

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/post-form@1",      "input": {        "url": "https://httpbin.org/post",        "body": {"name": "Ada", "tags": ["a", "b"], "count": 2}      }    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/post-form@1",  input: {    url: "https://httpbin.org/post",    body: { name: "Ada", tags: ["a", "b"], count: 2 },  },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/post-form@1",    "input": {        "url": "https://httpbin.org/post",        "body": {"name": "Ada", "tags": ["a", "b"], "count": 2},    },}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__post-form",    "arguments": {      "url": "https://httpbin.org/post",      "body": {"name": "Ada", "tags": ["a", "b"], "count": 2}    }  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__post-form with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: POST form (response recorded 2026-10-26). From the bundle's fixtures/post-form.json, not a live call.

json
{  "status": 200,  "content_type": "application/json",  "location": null,  "etag": null,  "body": {    "args": {},    "data": "",    "files": {},    "form": {"count": "2", "name": "Ada", "tags": ["a", "b"]},    "headers": {      "Accept": "application/json, text/*;q=0.9, */*;q=0.8",      "Accept-Encoding": "br, gzip, deflate",      "Accept-Language": "*",      "Content-Length": "30",      "Content-Type": "application/x-www-form-urlencoded",      "Host": "httpbin.org",      "Sec-Fetch-Mode": "cors",      "User-Agent": "b3os-actions/1 (+https://beta.b3os.org)"    },    "json": null,    "url": "https://httpbin.org/post"  }}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

`post-text`

POST text. POST a text body (plain text, CSV, XML, NDJSON, ...) with the content type you give and return the status and the response body. Not idempotent.

Ref io.b3os/http/post-text@1.0.0 · effect irreversible · no connection · MCP tool http__post-text

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/post-text@1",      "input": {        "url": "https://httpbin.org/anything/ingest",        "body": "id,value\n1,42\n",        "content_type": "text/csv"      }    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/post-text@1",  input: {    url: "https://httpbin.org/anything/ingest",    body: "id,value\n1,42\n",    content_type: "text/csv",  },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/post-text@1",    "input": {        "url": "https://httpbin.org/anything/ingest",        "body": "id,value\n1,42\n",        "content_type": "text/csv",    },}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__post-text",    "arguments": {      "url": "https://httpbin.org/anything/ingest",      "body": "id,value\n1,42\n",      "content_type": "text/csv"    }  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__post-text with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: POST text (response recorded 2026-10-26). From the bundle's fixtures/post-text.json, not a live call.

json
{  "status": 200,  "content_type": "application/json",  "location": null,  "etag": null,  "body": {    "args": {},    "data": "id,value\n1,42\n",    "files": {},    "form": {},    "headers": {      "Accept": "application/json, text/*;q=0.9, */*;q=0.8",      "Accept-Encoding": "br, gzip, deflate",      "Accept-Language": "*",      "Content-Length": "14",      "Content-Type": "text/csv",      "Host": "httpbin.org",      "Sec-Fetch-Mode": "cors",      "User-Agent": "b3os-actions/1 (+https://beta.b3os.org)"    },    "json": null,    "method": "POST",    "url": "https://httpbin.org/anything/ingest"  }}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

`put-json`

PUT JSON. PUT a JSON body to a URL (replace a resource) and return the status and the response body.

Ref io.b3os/http/put-json@1.0.0 · effect irreversible · no connection · MCP tool http__put-json

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/put-json@1",      "input": {        "url": "https://httpbin.org/put",        "body": {"name": "widget", "size": 3}      }    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/put-json@1",  input: {    url: "https://httpbin.org/put",    body: { name: "widget", size: 3 },  },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/put-json@1",    "input": {        "url": "https://httpbin.org/put",        "body": {"name": "widget", "size": 3},    },}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__put-json",    "arguments": {      "url": "https://httpbin.org/put",      "body": {"name": "widget", "size": 3}    }  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__put-json with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: PUT JSON (response recorded 2026-10-26). From the bundle's fixtures/put-json.json, not a live call.

json
{  "status": 200,  "content_type": "application/json",  "location": null,  "etag": null,  "body": {    "args": {},    "data": "{\"name\":\"widget\",\"size\":3}",    "files": {},    "form": {},    "headers": {      "Accept": "application/json, text/*;q=0.9, */*;q=0.8",      "Accept-Encoding": "br, gzip, deflate",      "Accept-Language": "*",      "Content-Length": "26",      "Content-Type": "application/json",      "Host": "httpbin.org",      "Sec-Fetch-Mode": "cors",      "User-Agent": "b3os-actions/1 (+https://beta.b3os.org)"    },    "json": {"name": "widget", "size": 3},    "url": "https://httpbin.org/put"  }}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

`patch-json`

PATCH JSON. PATCH a URL with a JSON body (partial update) and return the status and the response body.

Ref io.b3os/http/patch-json@1.0.0 · effect irreversible · no connection · MCP tool http__patch-json

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/patch-json@1",      "input": {"url": "https://httpbin.org/patch", "body": {"size": 4}}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/patch-json@1",  input: { url: "https://httpbin.org/patch", body: { size: 4 } },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/patch-json@1",    "input": {"url": "https://httpbin.org/patch", "body": {"size": 4}},}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__patch-json",    "arguments": {"url": "https://httpbin.org/patch", "body": {"size": 4}}  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__patch-json with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: PATCH JSON (response recorded 2026-10-26). From the bundle's fixtures/patch-json.json, not a live call.

json
{  "status": 200,  "content_type": "application/json",  "location": null,  "etag": null,  "body": {    "args": {},    "data": "{\"size\":4}",    "files": {},    "form": {},    "headers": {      "Accept": "application/json, text/*;q=0.9, */*;q=0.8",      "Accept-Encoding": "br, gzip, deflate",      "Accept-Language": "*",      "Content-Length": "10",      "Content-Type": "application/json",      "Host": "httpbin.org",      "Sec-Fetch-Mode": "cors",      "User-Agent": "b3os-actions/1 (+https://beta.b3os.org)"    },    "json": {"size": 4},    "url": "https://httpbin.org/patch"  }}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

`delete`

DELETE a URL. Send DELETE to a URL and return the status and the response body. Deleting cannot be undone.

Ref io.b3os/http/delete@1.0.0 · effect irreversible · no connection · MCP tool http__delete

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Idempotency-Key: 7c1e2f6a-1d43-4a8e-b2a5-3f0c9d5e8b11" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/http/delete@1",      "input": {"url": "https://httpbin.org/delete"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/http/delete@1",  input: { url: "https://httpbin.org/delete" },}, { idempotencyKey: crypto.randomUUID() });console.log(result.output);

python
import uuidfrom b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/http/delete@1",    "input": {"url": "https://httpbin.org/delete"},}, idempotency_key=str(uuid.uuid4()))print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "http__delete",    "arguments": {"url": "https://httpbin.org/delete"}  }}

Expose the pack as tools with --packs http on the local server or ?packs=http on the remote URL, and the agent calls http__delete with the action's input. The tool needs no connection. Without exposing the pack, actions_call takes the same input with ref.

Output, labeled fixture: DELETE a URL (response recorded 2026-10-26). From the bundle's fixtures/delete.json, not a live call.

json
{  "status": 200,  "content_type": "application/json",  "location": null,  "etag": null,  "body": {    "args": {},    "data": "",    "files": {},    "form": {},    "headers": {      "Accept": "application/json, text/*;q=0.9, */*;q=0.8",      "Accept-Encoding": "br, gzip, deflate",      "Accept-Language": "*",      "Host": "httpbin.org",      "Sec-Fetch-Mode": "cors",      "User-Agent": "b3os-actions/1 (+https://beta.b3os.org)"    },    "json": null,    "url": "https://httpbin.org/delete"  }}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

`pack_error.code`	Service status	Retryable	Message
`not_found`	404, 410	no	built from the service's response
`forbidden`	401, 403	no	built from the service's response
`rate_limited`	429	yes	rate limited (429); retry later
`invalid_request`	matched on the response body	no	built from the service's response

Was this page helpful?

Previous Hacker News

Next Hyperliquid (read-only)