# Basic information around IPFS pinning APIs

Braindump from @hsanjuan

-----

Data around pins (depending on where you are pinning, a pin has additional data attached):

- The root CID (always)
- Type
- Name or description? (Cluster for example)
- Replication factors and other options (Cluster)
- Duration / Cost / Submitted (I guess pinning services track how long something was pinned to bill the cost)
- Any metadata/tags (Cluster, Pinata I think too)
- Status (pinning/error/pinned)
- Progress (in number of DAG nodes pinned, as there is no general way to know the total % of a DAG (in unixfs DAGs yes, but this is not used))

------

Pinning process:

- Sync: the user needs to wait until it is pinned (ipfs)
- Async: the user submits the pin (cluster, other pinning services?) and the service pins in the background (potential callback informs the user when process done (i.e. in pinbots))

-----

Pin types:

* ipfs has 3 pin types: recursive, direct, indirect
* The users mostly use/worry about recursive and that's what most tools do (pinning services, pinbots etc)
* Cluster has a few types of pins (the normal one translates to a recursive one on IPFS, but there are also other to support sharded pins)

-----

Pin meaning:

- In IPFS it is a DAG (recursive-pins, as identified by its root CID) or a block (direct pins), to not be removed during Garbage Collection (GC)
- Anywhere else it is a DAG to be "stored". Out of all the things that pin, the only one that has GC is IPFS. Thus a pin has just mostly come to mean "Merkle-DAG". List my pins ~=~ List my Merkle-DAGs.
- The PINSET would be the list of pins.

-----

Common questions when pinning that ipfs ecosystem is bad at answering:

- Is it pinned?
- How long will it take?
- How big is this pin?

-----