01 / QUICK START

Write a sample and retrieve it.

Create a WORO account and verify your email. In the account portal, create a write token and copy it when it is shown; WORO will not show it again. Store it in a local secret manager or your deployment platform's secret store.

1. Write a sample value

curl --request POST \
  --url '{{API_BASE_URL}}/secret' \
  --header "x-api-key: $WORO_WRITE_TOKEN" \
  --header 'content-type: text/plain' \
  --data-binary 'hello from WORO'

WORO stores request-body bytes without text decoding or re-encoding. It preserves the request Content-Type as metadata and returns it with the original bytes; if you omit the header, WORO uses application/octet-stream. When a client accepts gzip and it saves at least 32 bytes, WORO sends a gzip-compressed response that HTTP clients decompress automatically. For files or other binary content, use --data-binary @./payload.bin.

A successful write returns HTTP 201. The JSON response contains the redeem token in token and the expiry time in expiresAt:

{
  "token": "<redeem-token>",
  "expiresAt": "<ISO-8601 timestamp>"
}

2. Share the redeem token, then retrieve the value

Send the redeem token to the intended recipient through a suitable channel. Anyone who has it can attempt retrieval, so keep it out of places where unintended people might see it.

curl --request GET \
  --url '{{API_BASE_URL}}/secret/<redeem-token>'

The response body contains the original bytes. WORO claims the exchange before reading it and deletes the stored copy on read. Only one concurrent request can claim it; other requests return 404.

Command-line client

The WORO CLI is being prepared for Linux, macOS, and Windows. It is designed to send and retrieve files as bytes, including through standard input and output. Prebuilt downloads and package-manager installations are not available yet; follow the Integrations page for their release status.

const apiBaseUrl = '{{API_BASE_URL}}';
const write = await fetch(`${apiBaseUrl}/secret`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.WORO_WRITE_TOKEN,
    'content-type': 'text/plain',
  },
  body: 'hello from WORO',
});
if (!write.ok) throw new Error(`Write failed: ${write.status}`);
const { token: redeemToken } = await write.json();

const read = await fetch(`${apiBaseUrl}/secret/${encodeURIComponent(redeemToken)}`);
if (!read.ok) throw new Error(`Read failed: ${read.status}`);
console.log(await read.text());

import os
import requests

api_base_url = '{{API_BASE_URL}}'
write = requests.post(
    f'{api_base_url}/secret',
    headers={'x-api-key': os.environ['WORO_WRITE_TOKEN']},
    data='hello from WORO',
    timeout=15,
)
write.raise_for_status()
redeem_token = write.json()['token']

read = requests.get(f'{api_base_url}/secret/{redeem_token}', timeout=15)
read.raise_for_status()
print(read.text)

02 / API CLIENTS

Import the requests into your workflow.

Download and import one collection file into your API client. The production API URL and sample values are included. Add your write token to the collection's writeToken variable, run the sample write, then copy the response's token into redeemToken before running the read request. The read retrieves and deletes the sample value.

When importing the OpenAPI contract into Bruno, choose the generated WORO production API environment to set baseUrl. Enter your write token in the write request's API Key authentication field; enter the redeem token in the read request's redeemToken path parameter.

03 / API REFERENCE

Two requests complete the exchange.

WORO deletes values on read. Unredeemed values expire after 14 days.

04 / SECURITY

Know what each token can do.

Write token: authorizes writes against your account and balance. Create it in the account portal, keep it out of source control and logs, and revoke it if exposed.

Redeem token: lets anyone who has it attempt to retrieve the associated value. It is not tied to a recipient's identity and does not require sign-in.

WORO can read unencrypted content while processing it. Data is encrypted at rest, but this is not end-to-end encryption. Encrypt the value before sending it if WORO must not be able to read it.

WORO uses a conditional claim so only one request can retrieve a stored value. A sender can check status or revoke a pending exchange in the signed-in account page. A redeemed status means WORO completed its retrieval operation; it cannot prove that the recipient received or retained the HTTP response.

05 / ERRORS AND LIMITS

Responses to handle.

402

The account has no available credits. Add credits before retrying.

403

The write token is invalid or revoked. Check the token or create a new one.

404

The redeem token is unknown, expired, or already redeemed.

413

The payload exceeds the 1 MiB request limit.

New verified accounts receive 30 credits. The minimum prepaid order is $1.00 AUD for 100 credits. The average price per credit falls linearly from $0.0100 to $0.0069 as the order value rises to Stripe's general $999,999.99 AUD charge limit. The account page shows the formula and exact total, including GST, before checkout. Billing is in AUD; your card issuer may add conversion or foreign-transaction fees. See your account to check the current balance.