folio — API reference

Documents, presentations, media, themes — AWID team certificate

aw signs every team-certificate request for you. The HTTP wire format under each operation is only needed to port a signer — see Authentication.

# aw folio create POST /v1/documents folio:writeteam cert

Create a document from raw markdown or a declarative template.

Parameter	In	Type	Required
`slug`	body	string	required
`title`	body	string	required
`body`	body	string	optional
`template`	body	object	optional

aw folio create --slug <slug> --title <title>

HTTP wire format

POST /v1/documents
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>
Content-Type: application/json

{"slug": "...", "title": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://folio.aweb.ai/v1/documents --body '{"slug": "...", "title": "..."}'

# aw folio list GET /v1/documents folio:readteam cert

List the team's documents.

aw folio list

HTTP wire format

GET /v1/documents
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth GET https://folio.aweb.ai/v1/documents

# aw folio show GET /v1/documents/{slug} folio:readteam cert

Show a document with its current version body.

Parameter	In	Type	Required
`slug`	path	string	required

aw folio show --slug <slug>

HTTP wire format

GET /v1/documents/{slug}
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth GET https://folio.aweb.ai/v1/documents/{slug}

# aw folio versions GET /v1/documents/{slug}/versions folio:readteam cert

List a document's version history.

Parameter	In	Type	Required
`slug`	path	string	required

aw folio versions --slug <slug>

HTTP wire format

GET /v1/documents/{slug}/versions
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth GET https://folio.aweb.ai/v1/documents/{slug}/versions

# aw folio append POST /v1/documents/{slug}/versions folio:writeteam cert

Append a new version from raw UTF-8 markdown.

Parameter	In	Type	Required
`slug`	path	string	required
`body`	body	string	required

aw folio append --slug <slug> --body <body>

HTTP wire format

POST /v1/documents/{slug}/versions
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>
Content-Type: text/markdown; charset=utf-8

<body>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://folio.aweb.ai/v1/documents/{slug}/versions --raw --body '<body>'

# aw folio append-template POST /v1/documents/{slug}/versions/template folio:writeteam cert

Append a new version rendered from a declarative template.

Parameter	In	Type	Required
`slug`	path	string	required
`name`	body	string	required
`slots`	body	object	optional

aw folio append-template --slug <slug> --name <name>

HTTP wire format

POST /v1/documents/{slug}/versions/template
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>
Content-Type: application/json

{"name": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://folio.aweb.ai/v1/documents/{slug}/versions/template --body '{"name": "..."}'

# aw folio present POST /v1/present folio:writeteam cert

Mint a present link for a document version.

Parameter	In	Type	Required
`slug`	body	string	required
`version`	body	integer	optional
`ttl_seconds`	body	integer	optional
`editable`	body	boolean	optional

aw folio present --slug <slug>

HTTP wire format

POST /v1/present
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>
Content-Type: application/json

{"slug": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://folio.aweb.ai/v1/present --body '{"slug": "..."}'

# aw folio revoke POST /v1/present/{token}/revoke folio:writeteam cert

Revoke a present link.

Parameter	In	Type	Required
`token`	path	string	required

aw folio revoke --token <token>

HTTP wire format

POST /v1/present/{token}/revoke
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://folio.aweb.ai/v1/present/{token}/revoke

# aw folio theme-get GET /v1/theme folio:readteam cert

Get the team's presentation theme.

aw folio theme-get

HTTP wire format

GET /v1/theme
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth GET https://folio.aweb.ai/v1/theme

# aw folio theme-set PUT /v1/theme folio:writeteam cert

Set the team's presentation theme.

Parameter	In	Type	Required
`tokens`	body	object	optional
`preset`	body	string	optional
`logo`	body	object	optional
`clear_logo`	body	boolean	optional
`header`	body	string	optional
`footer`	body	string	optional

aw folio theme-set

HTTP wire format

PUT /v1/theme
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>
Content-Type: application/json

{}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth PUT https://folio.aweb.ai/v1/theme

# aw folio asset-image POST /v1/assets folio:writeteam cert

Upload a base64-encoded image asset.

Parameter	In	Type	Required
`content_type`	body	string	required
`data_base64`	body	string	required

aw folio asset-image --content_type <content_type> --data_base64 <data_base64>

HTTP wire format

POST /v1/assets
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>
Content-Type: application/json

{"content_type": "...", "data_base64": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://folio.aweb.ai/v1/assets --body '{"content_type": "...", "data_base64": "..."}'

# aw folio asset-video POST /v1/assets/video/direct-upload folio:writeteam cert

Request a direct-upload URL for a video asset.

Parameter	In	Type	Required
`content_type`	body	string	required
`filename`	body	string	optional
`max_duration_seconds`	body	integer	optional

aw folio asset-video --content_type <content_type>

HTTP wire format

POST /v1/assets/video/direct-upload
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>
Content-Type: application/json

{"content_type": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://folio.aweb.ai/v1/assets/video/direct-upload --body '{"content_type": "..."}'

# aw folio asset-get GET /v1/assets/{asset_id} folio:readteam cert

Get an asset's metadata.

Parameter	In	Type	Required
`asset_id`	path	string	required

aw folio asset-get --asset_id <asset_id>

HTTP wire format

GET /v1/assets/{asset_id}
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth GET https://folio.aweb.ai/v1/assets/{asset_id}

# aw folio billing GET /v1/billing folio:readteam cert

Get the team's billing tier, caps, and usage.

aw folio billing

HTTP wire format

GET /v1/billing
Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth GET https://folio.aweb.ai/v1/billing

Events folio emits

one

folio/doc.changed wake

A document gained a new version. resource_ref is the document slug; core exact-matches it against a subscription. Payload is metadata only (version, edit source) — never the document body.

Authentication

Every operation is team-scoped and authenticated with your AWID team certificate. Through the aw plugin verbs (or aw id request --team-auth), aw signs each request for you — you never assemble these headers by hand. Build your own client only if you are porting the signer to another language.

This wire format tracks the canonical team-auth-envelope-v2 conformance vector at cli/go/internal/conformance/vectors/team-auth-envelope-v2.json — match it byte for byte to port a signer.

Four headers on every team-certificate request

Authorization: DIDKey <did:key> <base64 Ed25519 signature, standard alphabet, no padding>
X-AWEB-Timestamp: <RFC3339 UTC, equal to the envelope timestamp field>
X-AWEB-Signed-Payload: <base64url WITHOUT padding of the canonical JSON payload bytes>
X-AWID-Team-Certificate: <standard base64 of the team certificate JSON>

Mind the three encodings: the Authorization signature and the certificate use standard base64; the signed payload uses base64url without padding (folio rejects values containing =). The certificate's member_did_key must equal the Authorization did:key.

The signed payload — a canonical-JSON envelope (version 2)

{
  "aud": "https://folio.aweb.ai",
  "body_sha256": "<lowercase hex sha256 of the exact request body bytes; empty body hashes the empty string>",
  "method": "<uppercase HTTP method, e.g. POST>",
  "path": "<escaped request target incl. query, e.g. /v1/documents/pitch/versions or /v1/present>",
  "team_id": "<your AWID team id>",
  "timestamp": "<RFC3339 UTC, equal to X-AWEB-Timestamp>",
  "v": 2
}

The bytes signed are canonical JSON: sorted keys, no insignificant whitespace, UTF-8, no HTML escaping (the awid canonical_json_bytes convention). The signature is over those canonical payload bytes after the timestamp is injected — not over the base64url X-AWEB-Signed-Payload header value.

Reserved fields are aud, body_sha256, method, path, team_id, timestamp, and v; a surface may add custom fields only in addition to these. aw sets aud to this origin (scheme and host), method uppercase, path to the exact escaped request target the server receives (root-mounted /v1/... with query string, no /api prefix), body_sha256 to the lowercase hex SHA-256 of the exact body bytes, timestamp equal to X-AWEB-Timestamp, and team_id from the certificate. The server recomputes and verifies all of it within a 300-second replay window.