For agents, and the people who run them
Let your agent send the delivery.
Theirway has a public API. An agent holding a personal access token that you made can create a delivery of files, upload them, make your client's link, email it and read the checksums back. Your client still opens the link and downloads by hand.
This page as Markdown. The API as OpenAPI. For a crawler: llms.txt.
What an agent can do today
The web app and an agent use one API, so anything below is also what you can do by hand in the app. For a delivery of files, an agent can:
- Create a delivery drawn as Files, with release notes for the top of your client's page.
- Upload files up to your storage quota, in parts, straight to storage in France. Send each file's SHA-256 when you start the upload: an upload that sends none is stored without one.
- Make a link for your client, and email it from Theirway.
- Read back each file's size and SHA-256 (null for a file stored without one), and what has happened to the delivery.
- Keep a delivery up to date and snapshot each version, from a CI job: the calls, in order.
- Withdraw it by deleting the delivery. You can restore it for 30 days.
What it does not do
- No machine address for the latest build, and no webhooks. Your client downloads by hand, and nothing is pushed to an agent when they do. It can ask for the delivery's events.
- An agent cannot sign itself up. Accounts are invite only, and a token is made by a signed-in person, never by an agent. If you have no account, ask your human to join the waiting list, or write to hello@theirway.app.
- Checksums are as reported when the file was uploaded. Theirway keeps the SHA-256 you send and shows it beside the file. It does not work it out again. It helps your client notice a damaged download, and it does not say who made the file. Sign your builds.
First, a person makes a token
Sign in at theirway.app/app, open Access tokens, give the token a name, tick what it may do, choose how long it works (30 days, 90 days, or a year) and press Create token. It is shown once. Put it in an environment variable, THEIRWAY_TOKEN, and never in a URL, a query string or a file you commit. The agent sends it as Authorization: Bearer <token>. Revoke it on the same page at any time.
Give it the least it needs. An agent that sends deliveries needs these three, and nothing else:
| Scope | Ticked in the app as | What it lets the agent do |
|---|---|---|
deliveries:write | Create deliveries and upload | Create, upload, change the release notes, withdraw |
deliveries:read | See deliveries | Read the files, their checksums and the events |
recipients:send | Send to clients | Make a client's link and email it |
The form starts with See the account ticked too, and Send to clients off. Leave Send to clients off for an agent that only uploads: a link puts the files in front of another person. Leave Ask other people for files off too: it lets strangers send files into your storage.
The steps, with curl
These need curl and jq, and a file called setup-2.4.1.msi next to you. Every request is https://theirway.app/api/v1 plus a path; set THEIRWAY_API to use another server. A create takes an Idempotency-Key, so a retry after a timeout gives back the same delivery or link, not a second one.
Set up once
# THEIRWAY_TOKEN is in the environment: the token, not a placeholder.
API=${THEIRWAY_API:-https://theirway.app/api/v1}
api() { curl -sS --fail-with-body -w '\n' -H "Authorization: Bearer $THEIRWAY_TOKEN" "$@"; }
1. Create the delivery
presentation is "files" or "pictures", chosen now and never changed. description is the release notes: plain text, at most 10,000 characters.
FILE=setup-2.4.1.msi
SHA=$(sha256sum "$FILE" | cut -d' ' -f1) # on macOS: shasum -a 256
SIZE=$(wc -c < "$FILE" | tr -d ' ')
RUN=$(date +%s)-$RANDOM # keep one key per step if you retry
DELIVERY=$(api -X POST "$API/deliveries" \
-H "Idempotency-Key: delivery-$RUN" -H 'Content-Type: application/json' \
-d '{"title": "Build 2.4.1 for Acme", "client_name": "Acme",
"client_email": "it@acme.example", "presentation": "files",
"description": "Fixes the USB reconnect."}' | jq -r .id)
2. Upload the file
Four calls, and the bytes never pass through the API. Start the upload with the file's size and SHA-256: you get an uploadId and a key. Sign each part to get a URL, and PUT the part's bytes to it, straight to storage, with no token on that request; keep the ETag header of the answer. Complete with every part's number and ETag. Parts are 5 MiB or more, except the last, and at most 10,000 in all. A file under 5 MiB is one part. The size you declare must equal the bytes you upload, or completing answers 422. Completing answers 204, with no body: the id of the file it made is in the Theirway-File-Id header.
UPLOAD=$(api -X POST "$API/deliveries/$DELIVERY/uploads" \
-H "Idempotency-Key: upload-$RUN" -H 'Content-Type: application/json' \
-d "{\"filename\": \"$FILE\", \"type\": \"application/octet-stream\",
\"size\": $SIZE, \"relative_path\": \"$FILE\", \"sha256\": \"$SHA\"}")
UPLOADS="$API/deliveries/$DELIVERY/uploads/$(printf %s "$UPLOAD" | jq -r .uploadId)"
KEY=$(printf %s "$UPLOAD" | jq -r .key)
PART_SIZE=5242880
PART_COUNT=$(( (SIZE + PART_SIZE - 1) / PART_SIZE ))
PARTS='[]'
for N in $(seq 1 "$PART_COUNT"); do
URL=$(api "$UPLOADS/parts/$N?key=$KEY" | jq -r .url)
ETAG=$(dd if="$FILE" bs=$PART_SIZE skip=$((N - 1)) count=1 2>/dev/null |
curl -sS --fail -D - -o /dev/null -X PUT --data-binary @- "$URL" |
awk 'tolower($1) == "etag:" { print $2 }' | tr -d '\r')
PARTS=$(printf %s "$PARTS" | jq -c --argjson n "$N" --arg etag "$ETAG" \
'. + [{PartNumber: $n, ETag: $etag}]')
done
ANSWER=$(api -X POST "$UPLOADS/complete?key=$KEY" -D - \
-H 'Content-Type: application/json' -d "{\"parts\": $PARTS}")
FILE_ID=$(printf %s "$ANSWER" | awk 'tolower($1) == "theirway-file-id:" { print $2 }' | tr -d '\r')
If starting answers 409 conflict, you already store this exact file, and its detail names it: attach it instead with POST /deliveries/{id}/files. If an upload is interrupted, GET the upload to list the parts storage already has, and send the rest.
3. Make the link, and email it
Anyone holding the link can download the files, so treat it like the token. The email is fixed words from Theirway, with your account address as Reply-To, and it carries the link. The answer sent means Theirway handed it to its mail service, which is not delivered
.
RECIPIENT=$(api -X POST "$API/deliveries/$DELIVERY/recipients" \
-H "Idempotency-Key: link-$RUN" -H 'Content-Type: application/json' \
-d '{"name": "Acme IT", "email": "it@acme.example"}')
RECIPIENT_ID=$(printf %s "$RECIPIENT" | jq -r .id)
echo "$RECIPIENT" | jq -r .link
api -X POST "$API/deliveries/$DELIVERY/recipients/$RECIPIENT_ID/email"
4. Read the checksums and what happened
api "$API/deliveries/$DELIVERY/files" | jq -r '.files[] | "\(.sha256) \(.relative_path)"'
api "$API/deliveries/$DELIVERY/events" | jq -r '.items[].type'
The list pages at 100 files; pass next back as after for more. A file stored without a SHA-256 has null for it, so the first command prints null beside its name.
5. Withdraw it
api -X DELETE "$API/deliveries/$DELIVERY"
The same, in Python
Standard library only. It reads the whole file into memory to keep the example short; for a big file, read each part from disk.
import hashlib, json, os, pathlib, urllib.parse, urllib.request, uuid
API = os.environ.get("THEIRWAY_API", "https://theirway.app/api/v1")
TOKEN = os.environ["THEIRWAY_TOKEN"]
PART_SIZE = 5 * 1024 * 1024
RUN = uuid.uuid4().hex # a create's key is its step plus this: retry it with the same key
def call(method, path, body=None, key=None):
"""One API call as the token's holder: the answer's JSON, or None. A
create passes its key; every try of that step passes the same one."""
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
if key:
headers["Idempotency-Key"] = key
data = json.dumps(body).encode() if body is not None else None
request = urllib.request.Request(API + path, data, headers, method=method)
with urllib.request.urlopen(request) as response:
text = response.read()
return json.loads(text) if text else None
def upload(delivery_id, path):
data = path.read_bytes()
started = call("POST", f"/deliveries/{delivery_id}/uploads", {
"filename": path.name, "type": "application/octet-stream", "size": len(data),
"relative_path": path.name, "sha256": hashlib.sha256(data).hexdigest()},
key=f"upload-{RUN}")
base = f"/deliveries/{delivery_id}/uploads/{started['uploadId']}"
key = urllib.parse.quote(started["key"], safe="")
parts = []
for number, start in enumerate(range(0, len(data), PART_SIZE), start=1):
signed = call("GET", f"{base}/parts/{number}?key={key}")
put = urllib.request.Request(signed["url"], data[start:start + PART_SIZE], method="PUT")
with urllib.request.urlopen(put) as response: # storage: no token here
parts.append({"PartNumber": number, "ETag": response.headers["ETag"]})
call("POST", f"{base}/complete?key={key}", {"parts": parts})
delivery = call("POST", "/deliveries", {
"title": "Build 2.4.1 for Acme", "client_name": "Acme", "client_email": "it@acme.example",
"presentation": "files", "description": "Fixes the USB reconnect."},
key=f"delivery-{RUN}")
upload(delivery["id"], pathlib.Path("setup-2.4.1.msi"))
recipient = call("POST", f"/deliveries/{delivery['id']}/recipients",
{"name": "Acme IT", "email": "it@acme.example"}, key=f"link-{RUN}")
print(recipient["link"])
print(call("POST", f"/deliveries/{delivery['id']}/recipients/{recipient['id']}/email")["state"])
for file in call("GET", f"/deliveries/{delivery['id']}/files")["files"]:
print(file["sha256"], file["relative_path"])
call("DELETE", f"/deliveries/{delivery['id']}")
In a CI job: upload each build, then snapshot it
A CI job can keep one delivery up to date and, when a version ships, make a snapshot: a frozen copy of the files you choose, with its own link and one tag, such as v2.4.1, that never moves. The token needs deliveries:write and deliveries:read; add recipients:send only if the job also makes the snapshot's link. Nothing updates or snapshots by itself: the job asks.
- Once, a person or the first run creates the delivery (step 1 above), keeps its
idin a CI variable, and callsPUT /deliveries/{id}/modewith{"mode": "maintained"}. Only a delivery kept up to date can have snapshots. Asking for the mode it already has changes nothing. - Each build, upload the file as in step 2, with its SHA-256: a snapshot refuses a file that has none. Uploading the same name again adds a second file of that name beside the first.
- Keep the file's id. Completing the upload (step 2) names the file it made in the
Theirway-File-Idheader, so the job needs no search, and an earlier build of the same name is never mistaken for it. - Make the snapshot with
POST /deliveries/{id}/snapshots,{"tag", "note"?, "file_ids": [...]}and anIdempotency-Key. The answer is 200 with the snapshot'sid,tag,files,bytesandmanifest_sha256, the SHA-256 of its SHA256SUMS list. - Give the snapshot's link to your client. A snapshot is a delivery of its own: make its link as in step 3, with the snapshot's
id. It takes no more of your storage.
# Once: keep the delivery of step 1 up to date. $DELIVERY is its id.
api -X PUT "$API/deliveries/$DELIVERY/mode" \
-H 'Content-Type: application/json' -d '{"mode": "maintained"}'
# Each release, once the build is uploaded as in step 2: $FILE_ID is the
# file that upload made.
TAG=v2.4.1
SNAPSHOT=$(api -X POST "$API/deliveries/$DELIVERY/snapshots" \
-H "Idempotency-Key: snapshot-$DELIVERY-$TAG" -H 'Content-Type: application/json' \
-d "$(jq -n --arg tag "$TAG" --arg id "$FILE_ID" '{tag: $tag, file_ids: [$id]}')")
echo "$SNAPSHOT" | jq '{id, tag, files, manifest_sha256}'
A retry of the snapshot with the same key and body answers the first snapshot, not a second. The key belongs to your token and is kept 24 hours, so it names the delivery as well as the tag. After that, the same tag answers 409: a tag is never used twice, not even after its snapshot is erased. If a file cannot go in (retracted, removed by Theirway, or with no checksum), the answer is 409 snapshot-refused, it names every such file and why, and no snapshot is made.
Limits, and good manners
- Storage. Each account has a storage quota. A file that would take it past the quota is refused with 413, before any byte is sent.
- Time. A signed part URL works for an hour. An
Idempotency-Keyis remembered for 24 hours. - Email. The same link can be emailed once every 10 minutes. An account can email 20 links an hour and 50 a day. Theirway may also refuse an address, and does not say why. Copying the link and sending it yourself always works.
- Words. The email has no text of your own and no checksum in it. Send the checksum from your own mail, so your client can compare.
- Errors are
application/problem+json:typesays which, anddetailsays what to do next. A token without the scope gets a 403 that names it. - Emailing is you reaching a person. Do it only when the person who runs the agent said to.
The full list of routes, fields and answers is the OpenAPI document. Stored in the EU, with OVHcloud in France: see the privacy notice.
Join the waiting list.
Leave your email and we'll invite you when there's a place. Joining the list doesn't create an account.