---
layout: default
title: Folder
nav_order: 6
parent: Gateway
grand_parent: API
has_children: false
permalink: /api/gateway/folder.html
---

The **Folder** is a high-level abstraction that allows users to easily operate on their DAG, such as adding, updating, or removing links. While not a new concept, it simplifies multiple IPFS node operations into a single API. To enable smooth operations on TB-level single DAGs using a folder, users must first import their DAG into the folder using `PUT /api/v0/folder/{CID}`. This allows GW3 to shard the DAGs across multiple services. After that, `POST /folder/operation` can be used to update your DAGs.

# Folder Import

```bash
curl -X PUT "https://gw3.io/api/v0/folder/{cid}?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"
```

Import a previously pinned CID to the folder system. For large DAGs (with many links), consider setting an extended timeout period (1 second per link).

- **cid**
  - Required: Yes
  - Description: A CID that has already been pinned by GW3.
  - Example: `bafybeidbcbdlaqgn6yvp6wc4ca66jl2zazwbzh46qtvovpzznxgomjxtce`

- **ts**
  - Required: Yes
  - Description: A query parameter representing the current UNIX timestamp.
  - Example: `1688644825`

## Response body

```json
{
    "code": 200,
    "msg": "ok"
}
```

# Folder Operation

```bash
curl -X POST "https://gw3.io/api/v0/folder/operation?ts=$(date +%s)" \
   -H "X-Access-Key: YOUR_ACCESS_KEY" \
   -H "X-Access-Secret: YOUR_ACCESS_SECRET"
```

Specify the old CID root, links you want to add/update in the DAG, and links you wish to remove. The API will combine the changes into a new DAG and return it to the user.

- **ts**
  - Required: Yes
  - Description: A query parameter that represents the current UNIX timestamp.
  - Example: `1688644825`

- **cid**
  - Required: Yes
  - Description: A CID that has already been imported to the folder or generated by the folder.
  - Example: `bafybeidbcbdlaqgn6yvp6wc4ca66jl2zazwbzh46qtvovpzznxgomjxtce`

- **add**
  - Required: No
  - Description: An array of tuples specifying the link (name --> CID) you want to add to the DAG. If a link with the same name already exists in the old DAG, the old link will be replaced. All CIDs must be pinned by GW3 first.
  - Example: `[["my_license", "k2cwuee0yyjcb7195g3gkv0ejhp9b37zf3glzlayg5h81xgun5jd9x1i"]]`

- **remove**
  - Required: No
  - Description: Remove existing links in the DAG by their names.
  - Example: `["README.md"]`

- **pin_new**
  - Required: No
  - Description: Pin the new DAG. If the new CID is already pinned, the API will return an error.
  - Example: `true`

- **unpin_old**
  - Required: No
  - Description: Unpin the old DAG; this requires `pin_new` to be true. If the old DAG is still being used by another of your pinned DAGs, an error will be returned.
  - Example: `true`

## Request body

```json
{
   "cid":"k2cwuee0yyjcb7195g3gkv0ejhp9b37zf3glzlayg5h81xgun5jd9x1i",
   "remove":[
      "README.md",
      "package.json"
   ],
   "add":[
      ["test.config","k2jmtxts79pbodzrx8nyndvwvavvd70k3fnbo0ev1lc47ho40t98ocup"]
   ],
   "pin_new":true,
   "unpin_old":true
}
```

## Response Body

```json
{
    "code": 200,
    "msg": "ok",
    "data": {
        "cid": "QmPUmNQ76J748c3iboBCRnxSge39sftmn9zSyLXjA1GBvc"
    }
}
```

## Use Case Condition
1. All CIDs used in the /api/v0/folder/operation must be pinned by GW3 first.
2. Cannot add and remove the same link name in a single operation call.
```