Calling Endpoints

Endpoint URL

Every endpoint has the format:

https://api.wrapd.sh/v1/{username}/{endpoint-name}

The HTTP method must match what’s defined in your wrapd.yaml.

Headers

Header	Required	Description
X-API-Key	Yes (unless public)	Your API key
Accept	No	application/json for buffered JSON, default is SSE streaming
Content-Type	No	application/json when sending a request body

Passing arguments

Send arguments as a JSON body:

curl -X POST https://api.wrapd.sh/v1/alice/ping \
  -H "X-API-Key: wrapd_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"host": "google.com", "count": "5"}'

For GET endpoints with no arguments, just make the request:

curl https://api.wrapd.sh/v1/alice/uptime \
  -H "X-API-Key: wrapd_sk_your_key"

Response formats

JSON (buffered)

Set Accept: application/json to receive the complete output as JSON:

curl https://api.wrapd.sh/v1/alice/hello \
  -H "X-API-Key: wrapd_sk_your_key" \
  -H "Accept: application/json"

Without transformer:

{
  "output": "hello world\n",
  "exit_code": 0
}

With transformer:

{
  "data": {"cpu": 45, "mem": 72},
  "exit_code": 0
}

SSE (streaming)

By default, responses stream as Server-Sent Events:

curl -N https://api.wrapd.sh/v1/alice/deploy \
  -H "X-API-Key: wrapd_sk_your_key"

See Streaming (SSE) for details.

Public routes

These routes require no authentication:

Route	Description
GET /:username/badge.svg	Status badge — live SVG showing agent online/offline

Integration examples

The dashboard generates these snippets automatically for each endpoint. You can also use them as reference here.

curl

curl -N https://api.wrapd.sh/v1/alice/ping \
  -H "X-API-Key: wrapd_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"host": "google.com"}'

The -N flag disables output buffering so SSE chunks stream in real-time.

Python

import requests

response = requests.post(
    "https://api.wrapd.sh/v1/alice/ping",
    headers={
        "X-API-Key": "wrapd_sk_your_key",
        "Accept": "text/event-stream",
    },
    stream=True,
)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

Use stream=True and iter_lines() to consume the SSE stream incrementally.

JavaScript

const response = await fetch("https://api.wrapd.sh/v1/alice/ping", {
    method: "POST",
    headers: { "X-API-Key": "wrapd_sk_your_key" },
    body: JSON.stringify({ host: "google.com" }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    process.stdout.write(decoder.decode(value));
}

This fetch pattern works in both browser and Node.js.

n8n

Node type:    HTTP Request
Method:       POST
URL:          https://api.wrapd.sh/v1/alice/ping
Auth type:    Header Auth
  Name:       X-API-Key
  Value:      wrapd_sk_your_key
Response:     Return Full Response
Body type:    JSON
Body:         {"host": "google.com"}

Use “Return Full Response” to see the raw SSE stream.

Error responses

Status	Meaning
401	Missing or invalid API key
404	User or endpoint not found
429	Monthly execution limit exceeded
502	No agent connected, or execution failed

{
  "error": "No agent connected"
}