library — API reference

Catalog reads — no auth

three

# aw library list-blueprints GET /v1/blueprints library:readpublic

Browse the public blueprint catalog, optionally filtered by tag overlap.

Parameter	In	Type	Required
`tags`	query	array	optional

aw library list-blueprints

HTTP wire format

Raw HTTP, no auth — copy-paste runnable.

curl -s https://library.aweb.ai/v1/blueprints

# aw library get-blueprint GET /v1/blueprints/{blueprint_ref} library:readpublic

Get a public blueprint and its profile summaries.

Parameter	In	Type	Required
`blueprint_ref`	path	string	required

aw library get-blueprint --blueprint_ref aweb.team

HTTP wire format

Raw HTTP, no auth — copy-paste runnable.

curl -s https://library.aweb.ai/v1/blueprints/aweb.team

# aw library get-profile GET /v1/blueprints/{blueprint_ref}/profiles/{profile_ref} library:readpublic

Get a public profile's full content from the latest version of a blueprint.

Parameter	In	Type	Required
`blueprint_ref`	path	string	required
`profile_ref`	path	string	required

aw library get-profile --blueprint_ref aweb.team --profile_ref developer

HTTP wire format

Raw HTTP, no auth — copy-paste runnable.

curl -s https://library.aweb.ai/v1/blueprints/aweb.team/profiles/developer

Shelf, bindings, materialize, proposals — 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 library publish-blueprint POST /v1/blueprints/import library:writeteam cert

Publish or update a public blueprint. The body is the canonical import payload directly.

Parameter	In	Type	Required
`files`	body	array	required
`schema`	body	string	required

aw library publish-blueprint --files <files> --schema <schema>

HTTP wire format

POST /v1/blueprints/import
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

{"files": "...", "schema": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/blueprints/import --body '{"files": "...", "schema": "..."}'

# aw library register POST /v1/team/register library:writeteam cert

Parameter	In	Type	Required
`owner`	body	string	optional
`display_name`	body	string	optional

aw library register

HTTP wire format

POST /v1/team/register
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 POST https://library.aweb.ai/v1/team/register

# aw library create-shelf-profile POST /v1/profiles library:writeteam cert

Create a private shelf profile from a profile payload.

Parameter	In	Type	Required
`files`	body	array	required
`tags`	body	array	optional

aw library create-shelf-profile --files <files>

HTTP wire format

POST /v1/profiles
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

{"files": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/profiles --body '{"files": "..."}'

# aw library shelf-version POST /v1/profiles/{profile_ref}/versions library:writeteam cert

Add a new content version of an owned shelf profile.

Parameter	In	Type	Required
`profile_ref`	path	string	required
`files`	body	array	required

aw library shelf-version --profile_ref <profile_ref> --files <files>

HTTP wire format

POST /v1/profiles/{profile_ref}/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: application/json

{"files": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/profiles/{profile_ref}/versions --body '{"files": "..."}'

# aw library update-from-source POST /v1/profiles/{profile_ref}/update-from-source library:writeteam cert

Per-part 3-way merge of a shelf profile against a newer version of its source blueprint: pull upstream improvements into un-evolved parts, keep local edits. A real merge mints target_version; nothing pullable is a no-op.

Parameter	In	Type	Required
`profile_ref`	path	string	required
`target_version`	body	string	required
`source_blueprint_version`	body	string	optional

aw library update-from-source --profile_ref <profile_ref> --target_version <target_version>

HTTP wire format

POST /v1/profiles/{profile_ref}/update-from-source
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

{"target_version": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/profiles/{profile_ref}/update-from-source --body '{"target_version": "..."}'

# aw library import-to-shelf POST /v1/shelf/import library:writeteam cert

Copy a public-blueprint profile onto the team's private shelf. Idempotent per source profile: re-import returns the existing copy unchanged.

Parameter	In	Type	Required
`source_blueprint_ref`	body	string	required
`source_blueprint_version`	body	string	optional
`profile_ref`	body	string	required
`tags`	body	array	optional

aw library import-to-shelf --source_blueprint_ref <source_blueprint_ref> --profile_ref <profile_ref>

HTTP wire format

POST /v1/shelf/import
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

{"source_blueprint_ref": "...", "profile_ref": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/shelf/import --body '{"source_blueprint_ref": "...", "profile_ref": "..."}'

# aw library publish-profile POST /v1/profiles/{profile_ref}/publish library:writeteam cert

Publish a private shelf profile into a public blueprint (new blueprint or a new version of an owned blueprint); blueprint.yaml is library-generated and the profile set accumulates.

Parameter	In	Type	Required
`profile_ref`	path	string	required
`profile_version`	body	string	optional
`blueprint_version`	body	string	required
`target_blueprint_ref`	body	string	optional
`new_blueprint`	body	object	optional

aw library publish-profile --profile_ref <profile_ref> --blueprint_version <blueprint_version>

HTTP wire format

POST /v1/profiles/{profile_ref}/publish
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

{"blueprint_version": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/profiles/{profile_ref}/publish --body '{"blueprint_version": "..."}'

# aw library set-profile-tags PUT /v1/profiles/{profile_ref}/tags library:writeteam cert

Replace a profile's organizational tags.

Parameter	In	Type	Required
`profile_ref`	path	string	required
`tags`	body	array	required

aw library set-profile-tags --profile_ref <profile_ref> --tags <tags>

HTTP wire format

PUT /v1/profiles/{profile_ref}/tags
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

{"tags": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth PUT https://library.aweb.ai/v1/profiles/{profile_ref}/tags --body '{"tags": "..."}'

# aw library set-blueprint-tags PUT /v1/blueprints/{blueprint_ref}/tags library:writeteam cert

Replace a blueprint's organizational tags.

Parameter	In	Type	Required
`blueprint_ref`	path	string	required
`tags`	body	array	required

aw library set-blueprint-tags --blueprint_ref <blueprint_ref> --tags <tags>

HTTP wire format

PUT /v1/blueprints/{blueprint_ref}/tags
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

{"tags": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth PUT https://library.aweb.ai/v1/blueprints/{blueprint_ref}/tags --body '{"tags": "..."}'

# aw library bind POST /v1/agents/{agent_id}/profile-binding library:writeteam cert

Bind an agent identity to a profile ref/version/digest.

Parameter	In	Type	Required
`agent_id`	path	string	required
`profile_ref`	body	string	required
`profile_version`	body	string	required
`profile_digest`	body	string	required
`source_blueprint_ref`	body	string	optional

aw library bind --agent_id <agent_id> --profile_ref <profile_ref> --profile_version <profile_version> --profile_digest <profile_digest>

HTTP wire format

POST /v1/agents/{agent_id}/profile-binding
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

{"profile_ref": "...", "profile_version": "...", "profile_digest": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/agents/{agent_id}/profile-binding --body '{"profile_ref": "...", "profile_version": "...", "profile_digest": "..."}'

# aw library get-binding GET /v1/agents/{agent_id}/profile-binding library:readteam cert

Get the profile binding for an agent identity.

Parameter	In	Type	Required
`agent_id`	path	string	required

aw library get-binding --agent_id <agent_id>

HTTP wire format

GET /v1/agents/{agent_id}/profile-binding
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://library.aweb.ai/v1/agents/{agent_id}/profile-binding

# aw library shelf GET /v1/shelf library:readteam cert

List the team's shelf working set: each profile's latest version, source provenance, and whether a newer source-blueprint version is available.

aw library shelf

HTTP wire format

GET /v1/shelf
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://library.aweb.ai/v1/shelf

# aw library materialize POST /v1/materialize library:writeteam cert

Materialize a profile payload for a local or custodial runtime.

Parameter	In	Type	Required
`agent_id`	body	string	optional
`profile_ref`	body	string	optional
`runtime_kind`	body	string	required
`target`	body	string	required

aw library materialize --runtime_kind <runtime_kind> --target <target>

HTTP wire format

POST /v1/materialize
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

{"runtime_kind": "...", "target": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/materialize --body '{"runtime_kind": "...", "target": "..."}'

# aw library propose POST /v1/proposals library:writeteam cert

Submit an asset-scoped profile learning proposal. A profile proposal carries a changeset of file assets and profile.yaml field assets; approve applies it to the current shelf profile, auto-increments the next patch version, and mints after per-asset stale checks.

Parameter	In	Type	Required
`target`	body	string	required
`profile_ref`	body	string	optional
`content`	body	object	optional
`summary`	body	string	optional
`rationale`	body	string	optional

aw library propose --target <target>

HTTP wire format

POST /v1/proposals
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

{"target": "..."}

Hand-runnable with the aw CLI, no plugin:

aw id request --team-auth POST https://library.aweb.ai/v1/proposals --body '{"target": "..."}'

# aw library proposals GET /v1/proposals library:readteam cert

List the team's profile learning proposals.

aw library proposals

HTTP wire format

GET /v1/proposals
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://library.aweb.ai/v1/proposals

# aw library approve POST /v1/proposals/{proposal_id}/approve library:writeteam cert

Approve a profile learning proposal.

Parameter	In	Type	Required
`proposal_id`	path	string	required

aw library approve --proposal_id <proposal_id>

HTTP wire format

POST /v1/proposals/{proposal_id}/approve
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://library.aweb.ai/v1/proposals/{proposal_id}/approve

# aw library reject POST /v1/proposals/{proposal_id}/reject library:writeteam cert

Reject a profile learning proposal.

Parameter	In	Type	Required
`proposal_id`	path	string	required

aw library reject --proposal_id <proposal_id>

HTTP wire format

POST /v1/proposals/{proposal_id}/reject
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://library.aweb.ai/v1/proposals/{proposal_id}/reject

# aw library get-shelf-profile GET /v1/profiles/{profile_ref} library:readteam cert

Get the team's private shelf profile. ?include=files adds the profile content (path/content_utf8/sha256) so a local runtime can re-materialize the latest shelf version.

Parameter	In	Type	Required
`profile_ref`	path	string	required
`include`	query	string	optional

aw library get-shelf-profile --profile_ref <profile_ref>

HTTP wire format

GET /v1/profiles/{profile_ref}
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://library.aweb.ai/v1/profiles/{profile_ref}

# aw library delete-blueprint DELETE /v1/blueprints/{blueprint_ref} library:writeteam cert

Hard-delete a public blueprint your team owns (all versions). Shelf profiles that source-track it are detached, not orphaned. Irreversible.

Parameter	In	Type	Required
`blueprint_ref`	path	string	required

aw library delete-blueprint --blueprint_ref <blueprint_ref>

HTTP wire format

DELETE /v1/blueprints/{blueprint_ref}
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 DELETE https://library.aweb.ai/v1/blueprints/{blueprint_ref}

# aw library delete-shelf-profile DELETE /v1/profiles/{profile_ref} library:writeteam cert

Hard-delete one of your team's private shelf profiles (all versions), and its bindings and proposals. Irreversible.

Parameter	In	Type	Required
`profile_ref`	path	string	required

aw library delete-shelf-profile --profile_ref <profile_ref>

HTTP wire format

DELETE /v1/profiles/{profile_ref}
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 DELETE https://library.aweb.ai/v1/profiles/{profile_ref}

Authentication

The three public catalog reads take no auth. Every other 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 (Library 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://library.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/shelf/import or /v1/blueprints?tags=starter>",
  "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.