Image Services

Create a delivery token

POST /v1/images/keys · scope images:keys · reversible · idempotent

Returns the full imgt_… token, exactly once: only its hash is stored, so there is no way to show it again. If it is lost, rotate or mint another.

This token does not work against this API: it authenticates the delivery plane — GET {api_endpoint}/v1/img?url=… for transformations and POST {api_endpoint}/v1/sign to sign URLs. Delivery deliberately does not go through api.truo.cloud: one extra hop on every <img> of every page is one extra failure mode.

It requires images:keys rather than images:write because holding this token is the ability to serve — and bill — traffic through the account’s tenant.

curl https://api.truo.cloud/v1/images/keys \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images key create

await truo.images.keys.create();

truo_images({
  "action": "key_create"
})

operationId: images.keys.create

Rotate the delivery token

POST /v1/images/keys/rotate · scope images:keys · destructive — cannot be undone · idempotent

Issues a new token and returns it. With grace_seconds, the previous token keeps working that long, so servers holding it do not fail at the instant of rotation; with 0 (the default) it dies immediately. There is no going back: the old token cannot be reactivated.

curl https://api.truo.cloud/v1/images/keys/rotate \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images key rotate

await truo.images.keys.rotate();

truo_images({
  "action": "key_rotate"
})

operationId: images.keys.rotate

Allow an origin

POST /v1/images/origins · scope images:write · reversible · idempotent

Adds a hostname (images.example.com) or a wildcard (*.example.com) to the allowlist. Idempotent: re-adding an existing pattern changes nothing. Each plan caps how many origins it can hold; past the cap this returns quota_exceeded.

curl https://api.truo.cloud/v1/images/origins \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

truo images origin add <pattern>

await truo.images.origins.add({});

truo_images({
  "action": "origin_add"
})

operationId: images.origins.add

List the origin allowlist

GET /v1/images/origins · scope images:read

The hostnames the service is allowed to fetch from. Fail-closed: an empty allowlist serves nothing, on purpose — an open image proxy is an attack tool.

curl https://api.truo.cloud/v1/images/origins \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images origin list

await truo.images.origins.list();

truo_images({
  "action": "origin_list"
})

operationId: images.origins.list

Remove an origin

DELETE /v1/images/origins/{pattern} · scope images:write · reversible · idempotent

Stops serving from that origin immediately. Reversible: adding the pattern back restores it. If it was the last origin, the tenant serves nothing until one is added — the allowlist is fail-closed.

curl https://api.truo.cloud/v1/images/origins/cdn.example.com \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images origin remove cdn.example.com

await truo.images.origins.remove("cdn.example.com");

truo_images({
  "action": "origin_remove",
  "pattern": "cdn.example.com"
})

operationId: images.origins.remove

Reveal the URL-signing secret

POST /v1/images/signing-secret · scope images:keys

Returns the per-tenant HMAC-SHA256 secret that signs delivery URLs. It is a POST on purpose, even though it changes nothing: a GET that returns a secret lands in browser history, in any proxy’s cache, and in yesterday’s curl. A POST forces a deliberate action, is not cacheable, and enters the audit log as a mutation.

The secret is recoverable (stored, not hashed) because your server needs it whole to sign every URL it emits. It belongs on the server, never in the browser: anyone holding it can mint URLs that serve — and bill — through your tenant. If it was compromised, rotate it with POST /v1/images/signing-secret/rotate.

curl https://api.truo.cloud/v1/images/signing-secret \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images signing reveal

await truo.images.signing.reveal();

truo_images({
  "action": "signing_reveal"
})

operationId: images.signing.reveal

Rotate the URL-signing secret

POST /v1/images/signing-secret/rotate · scope images:keys · destructive — cannot be undone · idempotent

Issues a new secret and returns it. URLs signed with the previous secret keep working until previous_valid_until (per grace_seconds) — without a grace window, every <img> already rendered in your pages would break at the instant of rotation. Re-sign and redeploy before the window closes.

curl https://api.truo.cloud/v1/images/signing-secret/rotate \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images signing rotate

await truo.images.signing.rotate();

truo_images({
  "action": "signing_rotate"
})

operationId: images.signing.rotate

Get the account’s Image Services

GET /v1/images · scope images:read

It takes no id: there is one Image Services tenant per account. Returns the plan, the month’s usage, and how many origins are allowed. origin_count: 0 means nothing is served yet — the allowlist is fail-closed. If the account does not have the service, it returns 404.

curl https://api.truo.cloud/v1/images \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images get

await truo.images.tenant.get();

truo_images({
  "action": "get"
})

operationId: images.tenant.get

Get the period’s usage and billable line

GET /v1/images/usage · scope images:read

Consumption against the plan for the period: transformations (cache misses — real CPU work), deliveries, egress bytes, what the quota includes, the overage, and the total in USD. Includes the daily series. On a hard-capped plan (included.hard_cap) the overage is never billed: the service stops at the quota instead.

curl https://api.truo.cloud/v1/images/usage \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo images usage

await truo.images.usage.get();

truo_images({
  "action": "usage"
})

operationId: images.usage.get