Skip to content

Commit dff1453

Browse files
KzoepsKzoeps
committed
docs: add Hyperscan documentation
1 parent 8deed4e commit dff1453

4 files changed

Lines changed: 131 additions & 2 deletions

File tree

‎lib/navigation.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ export const navigation = [
5454
{ title: "Scaffold Starter App", path: "/tools/scaffold" },
5555
{ title: "Hypercerts CLI", path: "/tools/hypercerts-cli" },
5656
{ title: "Hyperindex", path: "/tools/hyperindex" },
57+
{ title: "Hyperscan", path: "/tools/hyperscan" },
5758
{ title: "Hyperboards", path: "/tools/hyperboards" },
5859
{ title: "Labelers", path: "/tools/labelers" },
5960
],

‎pages/reference/certified-services.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ For full PDS details (versions, active test instances, and guidance), see [Certi
3232

3333
| Service | Public URL | Purpose |
3434
|---|---|---|
35-
| Hyperscan | [`www.hyperscan.dev`](https://www.hyperscan.dev) | Ecosystem-wide view of indexers and related discovery infrastructure |
35+
| [Hyperscan](/tools/hyperscan) | [`www.hyperscan.dev`](https://www.hyperscan.dev) | Ecosystem-wide view of indexers and related discovery infrastructure |
3636

3737
## Labelers
3838

‎pages/tools/hyperindex.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Indexers handle that job. They consume network events, fetch and parse records b
2424

2525
Hyperindex is the reference indexer used in this ecosystem.
2626

27-
If you want to inspect indexers running across the broader ecosystem, use [Hyperscan](https://www.hyperscan.dev).
27+
If you want to inspect indexers running across the broader ecosystem, use [Hyperscan](/tools/hyperscan).
2828

2929
## How it works
3030

‎pages/tools/hyperscan.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Hyperscan
3+
description: Explorer for Hypercerts and related ATProto data across the Hypersphere network.
4+
---
5+
6+
# Hyperscan
7+
8+
Hyperscan is the public explorer for Hypercerts and related ATProto data in the Hypersphere ecosystem. Use it to see what is being published, inspect accounts and records, monitor the network, and understand the live infrastructure around Hypercerts.
9+
10+
Live at [hyperscan.dev](https://www.hyperscan.dev).
11+
12+
## What it is for
13+
14+
Hyperscan gives builders and reviewers a practical view into the public state of the network. It is useful when you want to:
15+
16+
- Browse recent hypercert activity without writing a query
17+
- Check whether a record was published and indexed correctly
18+
- Inspect a DID, handle, AT-URI, collection, or PDS host
19+
- See which collections and record types are active across the ecosystem
20+
- Monitor indexers, labelers, and live event streams
21+
- Give scripts or AI agents markdown endpoints for reading ecosystem state
22+
23+
## Feed
24+
25+
The [Feed](https://www.hyperscan.dev/feed) is the quickest way to see recent Hypercerts activity. It shows recently indexed records with links back into the underlying accounts and record details.
26+
27+
Use the feed when you want to answer questions like:
28+
29+
- What hypercerts were published recently?
30+
- Which accounts are publishing activity or contributor records?
31+
- Did my newly created record appear in the public index?
32+
- What records are available for review, comments, or presentation in Hyperboards?
33+
34+
The feed supports source and type filtering. For example, you can focus on Hypercerts records or a custom source, then narrow the list by record type such as activity or contributor records.
35+
36+
Each feed item links to the account and the indexed record in the Data Explorer. Hypercert activity cards can also link to a Hyperboard when one is available. Review and comment links take you to the review flow for that record.
37+
38+
### Feed views
39+
40+
The feed includes multiple ways to inspect activity:
41+
42+
| View | Use it for |
43+
|---|---|
44+
| Feed | Reading recent records as cards in chronological order |
45+
| Map | Seeing geographic context when records include location data |
46+
| Events | Watching indexed events in a more event-oriented format |
47+
48+
For most workflows, start with the Feed view. Switch to Map when location matters, or Events when you are checking indexing behavior and record arrival order.
49+
50+
## Data Explorer
51+
52+
The [Data Explorer](https://www.hyperscan.dev/data) is the main inspection tool. It lets you look up public ATProto data by DID, handle, AT-URI, or PDS host.
53+
54+
The Data Explorer is heavily inspired by [pdsls.dev](https://pdsls.dev), adapted for exploring Hypercerts and related Hypersphere records.
55+
56+
Use the Data Explorer when you need to validate or debug records:
57+
58+
- Paste a DID or handle to inspect an account's public repo data
59+
- Paste an AT-URI to jump directly to one record
60+
- Check which collections are present for an account
61+
- Compare a rendered feed card with the underlying record fields
62+
- Confirm that linked records, such as contributors or context records, exist publicly
63+
- Inspect example accounts before building your own publishing flow
64+
65+
This is especially helpful after creating data with the Scaffold app, the Hypercerts CLI, or a custom ATProto client. If the record appears in the Data Explorer, it has been published to the account's repo and can be discovered by the broader ecosystem.
66+
67+
## Infrastructure Views
68+
69+
Hyperscan also gives a compact overview of the infrastructure around Hypercerts. These pages are useful for understanding network health and data coverage without running your own monitoring stack.
70+
71+
| Page | What it shows |
72+
|---|---|
73+
| [Stats](https://www.hyperscan.dev/stats) | Network-level counts, collection breakdowns, participants, and indexed record totals |
74+
| [Stream](https://www.hyperscan.dev/stream) | Live network events as they arrive from the indexed stream |
75+
| [Indexers](https://www.hyperscan.dev/indexers) | Curated ATProto indexers and their status context |
76+
| [Labeler](https://www.hyperscan.dev/labeler) | Labeling services that evaluate records and publish reusable ATProto labels |
77+
78+
Together, these views help explain what infrastructure is present around Hypercerts: indexers gather and normalize public records, stats summarize the indexed network, streams show live ingestion, and labelers publish quality or trust signals that other apps can consume.
79+
80+
## Agent API
81+
82+
Hyperscan includes markdown endpoints designed for scripts and AI agents. These endpoints avoid HTML parsing and return readable summaries of the network, records, schemas, and write guides.
83+
84+
Start with the capabilities manifest:
85+
86+
```bash
87+
curl https://www.hyperscan.dev/agents
88+
```
89+
90+
Common read endpoints:
91+
92+
| Endpoint | What it returns |
93+
|---|---|
94+
| `/agents` | Capabilities manifest and endpoint index |
95+
| `/agents/stats` | Network snapshot with record counts, collections, and recent hypercerts |
96+
| `/agents/feed` | Recent Hypercerts records |
97+
| `/agents/profile/{handle-or-did}` | Account profile, collections, and recent records |
98+
| `/agents/lexicon` | Index of curated lexicon schemas |
99+
| `/agents/lexicon/{nsid}` | Detail for one lexicon schema |
100+
| `/agents/guides` | Index of write guides and common record-creation patterns |
101+
102+
Examples:
103+
104+
```bash
105+
# Current network snapshot
106+
curl https://www.hyperscan.dev/agents/stats
107+
108+
# Recent activity
109+
curl https://www.hyperscan.dev/agents/feed
110+
111+
# Inspect one account
112+
curl https://www.hyperscan.dev/agents/profile/daviddao.org
113+
114+
# Read the activity claim schema
115+
curl https://www.hyperscan.dev/agents/lexicon/org.hypercerts.claim.activity
116+
117+
# Find write guides for creating records
118+
curl https://www.hyperscan.dev/agents/guides
119+
```
120+
121+
Use the Agent API when you want a tool, bot, or coding agent to understand the current network state before deciding what to query, inspect, or create next.
122+
123+
## See also
124+
125+
- [Hyperindex](/tools/hyperindex) — indexer used to query and serve indexed Hypercerts data
126+
- [Labelers](/tools/labelers) — ATProto label services used for quality and trust signals
127+
- [Hypercerts CLI](/tools/hypercerts-cli) — command-line tool for creating and inspecting Hypercerts records
128+
- [Introduction to Lexicons](/lexicons/introduction-to-lexicons) — schemas behind the records shown in Hyperscan

0 commit comments

Comments
 (0)