> For the complete documentation index, see [llms.txt](https://docs.neova.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neova.io/neova/peer-to-peer-network/private-indexer.md).

# Private Indexer

The HTTP directory of the Neova private swarm. One request returns the nodes that hold a CID, already ranked.

A private swarm has no public DHT. Something else has to answer the only question that matters at read time: which nodes hold this CID, and which of them is worth asking first?

The **Private Indexer** is that directory. Neova specified it, published it, and runs it. It is a plain HTTP service. A node participates with one call, `POST /announce`, and a JSON body. Kubo, Helia, or a custom implementation can all speak it. There is no advertisement chain to build and no gossip protocol to join.

The specification is public: [Optimizing Private IPFS: Building a Private Indexer for Swarmkey'd Networks](https://discuss.ipfs.tech/t/optimizing-private-ipfs-building-a-private-indexer-for-swarmkeyd-networks/20081).

### What stock IPNI leaves unfinished

The public IPFS indexer, IPNI, was designed for the open network. Providers publish an IPLD advertisement chain. The indexer pulls that chain. Records come back as a list of peers, with no freshness rank, no latency, and no success rate. Private operators hit the same walls every time:

* the announce format and the choice of transport have never been strict enough to behave the same way across Kubo versions;
* an advertisement chain is a heavy machine for a swarm of tens or hundreds of nodes;
* public ingest endpoints assume a node the internet can reach;
* clients that miss often fall back to the DHT, which a private swarm has turned off.

The Private Indexer uses a push. The node sends the CIDs it actually pins. The indexer answers with providers already sorted.

### The path through the swarm

```
Kubo node
    │  pin list, about every 30s
    ▼
Announcer  ── POST /announce ──►  Private Indexer
             JSON                     CID → providers
                                      score, latency, availability
                                          │
Swarm Accelerator  ◄── GET /providers?cid=… 
```

#### Announce

The **announcer** sits beside Kubo. On a short interval, about **30 seconds**, it reads `pin/ls` and pushes the CIDs that are new. About every **12 hours** it re-announces the full set, which refreshes every record’s lifetime. Batches default to about **1,000 CIDs**, so a node with a large pinset does not open one request per file.

The body is a single JSON object:

* peer id and multiaddrs;
* the CID list;
* the metadata a production swarm needs: operator identity, provider name, node name, announced storage capacity.

There is no IPLD link, no entry chunk of 16,384 hashes, and no contextual metadata blob to decode. Re-announcing extends the TTL. The record stays discoverable for as long as the node keeps saying it has the content.

#### Lookup

`GET /providers?cid=…` returns the providers for that CID, best first. The order is a weighted score:

| Signal       | Weight | What it measures                       |
| ------------ | ------ | -------------------------------------- |
| Success rate | 0.4    | How often reads from this peer succeed |
| Freshness    | 0.3    | How recently the peer announced        |
| Latency      | 0.3    | Round-trip time from background probes |

A prober opens TCP checks to announced multiaddrs about every **30 seconds**, with a timeout of a few seconds, and keeps a short window of samples. An unreachable peer sinks in the ranking while it is still failing, which is earlier than a user would notice a hung download.

Lookup is one request and one response. That is the gain over a multi-hop DHT walk, and it is available only because the registry is explicit.

#### Lifetime, auth, and peers

Records live for **24 hours** by default. A background sweep, about every **5 minutes**, drops whatever has expired. A node that goes quiet leaves the catalog on that timer. The announce token and an allowlist of peer ids keep the registry inside the swarm. This directory is for members.

The indexer also exposes the peer list the rest of Neova trusts for operations: who is connected, who looks available, when they were last seen, and how healthy they are. Operator points are computed from that view. A machine that was registered and then disappeared does not keep earning. See Node operators.

### Where NeoDrive uses it

On the user path, NeoDrive writes to Kubo and redirects downloads to the accelerator. The accelerator is the component that calls `GET /providers`. The drive’s index and the swarm’s indexer answer different questions. The first knows the file is yours. The second knows which nodes can serve its CID.

A new upload becomes discoverable once the announcer’s next pass runs, so typically within half a minute. Until then, the file is already in your account and already pinned. The directory catches up, and subsequent reads go through the ranked list.

### Side by side

|           | IPNI                                     | Private Indexer                                 |
| --------- | ---------------------------------------- | ----------------------------------------------- |
| Announce  | HTTP PUT or gossipsub, loosely specified | `POST /announce` with a JSON body               |
| Payload   | IPLD advertisement chain                 | Flat CID list plus metadata                     |
| Direction | Indexer pulls                            | Provider pushes                                 |
| Lookup    | Unordered provider records               | Scored providers, with latency and availability |
| Lifetime  | Append-only chain                        | Explicit TTL, then garbage collection           |
| Access    | Public                                   | Bearer token and peer allowlist                 |
| Health    | None in the record                       | Background RTT probes                           |
| Fits      | The public network                       | A swarm-key network                             |