Specification
HAP v0.2
Human-readable specification for the Human Agent Protocol.
0. v0.1 → v0.2 changelog
v0.2 is a purely additive bump on top of v0.1: every v0.1 reader continues to parse v0.2 payloads without modification (unknown top-level keys are ignored per JSON's open-world model). Implementations targeting v0.2 add two optional discovery primitives:
freshness— last-updated timestamp plus a recommended next-refetch hint so agents avoid unnecessary polling.top_positions— a recency-ordered preview (max 5) of the expert's published positions, so agents can find topics without a follow-up index crawl.
The hap_version field bumps from "0.1" to "0.2". Detectors should accept either string. No fields are removed, renamed, or have changed semantics.
1. Overview
A HAP file is a JSON document published at /.well-known/hap.json on any domain. It declares an expert's identity, their knowledge offerings, and the agent endpoint that can answer queries on their behalf.
The goal is simple: let any AI agent discover and query any human expert, with structured access controls and verifiable identity. The file is not included in sitemaps and is blocked by robots.txt — it exists for machine-to-machine agent discovery only.
2. File location
The canonical location is https://<domain>/.well-known/hap.json. Agents should look here first. Alternative locations may be specified via a Link header or HTML <link> element with rel="hap".
3. Top-level fields
hap_version string Yes Protocol version. Currently "0.2". Detectors should accept "0.1" as well. identity object Yes Identity of the expert or organization. offerings array Yes Knowledge offerings available for query. agent object Yes Agent endpoint configuration. terms object Yes Access tier definitions keyed by tier name. meta object Yes Publication metadata. freshness object v0.2+ Last-updated timestamp + recommended next-refetch hint. See §9. top_positions array v0.2+ Recency-ordered preview of the expert's published positions (max 5). See §10. 4. Identity object
type string Yes "individual" or "organization". display_name string Yes Human-readable name shown in agent discovery results. name string Yes Canonical name (same as display_name in v0.1). bio string No Short biography. Truncated to 500 characters. tags array Yes Discovery keywords derived from position content. Max 20 items. verified boolean Yes true when identity has been verified by Deslop. 5. Offerings array
Each element in offerings describes a knowledge domain the expert covers.
type string Yes Offering type. Currently "expertise". domain string Yes Primary domain of expertise. topics array Yes List of topic titles the expert holds positions on. thesis string No Overall thesis or contrarian take. Truncated to 500 characters. 6. Agent object
protocol string Yes Transport protocol. Currently "mcp". endpoint string Yes URL of the queryable MCP endpoint for this expert. query_schema object Yes Input schema for queries. Fields: input (string), context (optional string). capabilities array Yes Supported operations: query, deep_dive, cite_sources. 7. Access tiers
The terms object contains one key per access tier present in the expert's published content.
Tiers not present in the content are omitted.
public terms.public If present Queryable by any agent without authentication. Has description (string) and rate_limit (e.g. "10 queries/day"). agent_gated terms.agent_gated If present Requires the requesting agent to identify itself. Has description (string) and requires: "agent_authentication". Identity is the price — not money. 8. Meta object
published string Yes ISO 8601 date the feature was published (YYYY-MM-DD). platform string Yes Originating platform. Value: "deslop". profile_url string Yes Human-readable profile URL for this expert. hap_spec_url string Yes URL of the HAP specification this file conforms to. 9. Freshness object (v0.2+)
freshness tells agents how recent the HAP payload is and how often they should re-fetch it. Both timestamps are ISO 8601 (RFC 3339) UTC strings.
last_updated string (ISO 8601) v0.2+ Most recent updated_at across the expert's published features. Strictly monotonic with respect to the expert's content edits. next_recommended_refetch string (ISO 8601) v0.2+ Heuristic re-fetch hint. +24h if the expert published any feature in the last 14 days (active burst), else +7d (dormant — daily refetch is wasteful). Agents are free to refetch sooner; this is a recommendation, not a directive. 10. Top positions array (v0.2+)
top_positions is a recency-ordered preview of the expert's published positions, capped at 5 entries ordered by published_at descending. It exists so agents can sniff what an expert covers without a follow-up index crawl. Each entry has the following fields.
title string v0.2+ Position title. thesis string v0.2+ Position-level thesis (per-position, NOT the creator-level offerings[].thesis). Truncated to 500 characters. url string v0.2+ Apex full URL of the position page: https://deslop.media/{username}/{seo_slug}/. published_at string (ISO 8601) v0.2+ Parent feature's published_at timestamp, UTC. 11. Discoverability crossrefs (deslop.media)
On deslop.media, every feature page advertises its HAP file via four independent surfaces so an agent finds the HAP regardless of which discovery primitive it inspects. This is implementation guidance for the publisher — the protocol itself doesn't mandate any specific crossref shape.
JSON-LD subjectOf: { "@type": "DataDownload", encodingFormat, contentUrl } Feature page Person schema Use subjectOf (not hasPart). DataDownload is the schema.org primitive for a machine-readable alternate. HTTP Link header <url>; rel="alternate"; type="application/json"; profile="..." Middleware on all feature URLs RFC 8288. Profile URL points back at this spec page so agents can verify the version they're parsing. HTML <link rel> <link rel="alternate" type="application/json" href="..."/> Feature page <head> HTML5 dropped the <link profile> attribute; profile lives in the HTTP Link header. Sitemap <xhtml:link rel="alternate" type="application/json" href="..."/> Feature URL <url> entries in /sitemap.xml Requires xmlns:xhtml namespace on the root <urlset>.
All four surfaces point at the same canonical URL: https://deslop.media/{username}/.well-known/hap.json. The api.deslop.media subdomain is backend implementation and is never the canonical URL agents follow.
12. Implementation notes
Agents discovering a hap.json should cache the file for no longer than the Cache-Control header specifies (default: 1 hour). Agents should include a User-Agent header identifying themselves and their human operator when querying endpoints.
Deslop-generated HAP files are served at the canonical URL
https://deslop.media/{username}/.well-known/hap.json.
This is the URL agents should index and follow. The file is not linked
from any page and is excluded from sitemaps.
The api.deslop.media subdomain is Deslop's backend
implementation detail. The endpoint
api.deslop.media/feature/{username}/.well-known/hap.json
is the upstream generator but is not the canonical URL — agents should
use the apex domain URL above.