# Welcome to Storedat! Welcome to the Storedat API (In Beta)! Here you'll find all the documentation you need to get up and running ### What is Storedat? [**Storedat**](https://www.storedat.io) **is a GraphQL abstraction layer built on top of web3 storage providers like Arweave and Filecoin** to be able to provide a seamless and consistent experience when reading via a single api-key driven integration. ### Mission **Storedat's mission** is to **provide a better user experience for both web2 and web3 users wanting to take advantage of decentralized storage**. We want to make decentralized storage accessible to all so that anyone can use it without having to deal with its complexities. **No dealing with wallets, signing transactions, managing private keys, paying transaction costs, and so on**. Just plug in and Storedat. **One API. One Integration. Web3 Storage made easy!** ### Why does Storedat exist? **We exist to accelerate the adoption of decentralized storage** by providing a **provider agnostic** way to read with those protocols all the while **abstracting away web3 from the user**. While we might start with Filecoin and Arweave today, our vision is to expand out and support more storage providers as well in the future. The **ultimate goal** is to have the **Storedat become the** **goto hub for anyone to plug and play with decentralized storage.** ## Want to jump right in? If you're eager to start playing around with the API, check out the getting started guide below :point\_down: {% content-ref url="/pages/eIVUS03JNahoQ94xMY9g" %} [Getting started](/getting-started) {% endcontent-ref %} ## Want to deep dive? Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API: {% content-ref url="/pages/0iN0n9wO3MylBDdSjXX3" %} [API Reference](/reference/api-reference) {% endcontent-ref %} # Decentralized Storage Overview Use this page to get a high level overview of what decentralized storage is if you are new to the space ### What is Web3? Web3 refers to the next generation of the World Wide Web built on decentralized technologies such as blockchain and peer-to-peer networks, which allow users to interact with each other in new and innovative ways. This is in contrast to the current version of the web (aka Web2) which is dominated by centralized platforms who brought upon the rise of social media, interactive design, cloud computing and eCommerce. ### What's a decentralized storage? Decentralized storage is a way of storing data that doesn't rely on a single, central location or authority. Instead, the data is distributed across many different devices or nodes, which are all connected to each other through a network. This allows for greater security and resilience, as the data is not stored in a single vulnerable location and can still be accessed even if some of the nodes go offline. A large portion of the data that is uploaded to decentralized storage networks today is public in that anyone can access it knowing the right identifier. ### Why should someone use decentralized over centralized storage? There are several reasons why someone might prefer to use decentralized storage over a centralized storage. One of the main advantages is increased security and resilience. Because the data is distributed across many different nodes and permanently stored, the data becomes more resilient to outages and removal from a central authority. Additionally, decentralized storage typically works off of a pay once, store forever model whereas a centralized storage (i.e. database, s3, etc...) requires monthly hosting/access/backup costs depending on the provider. With the Storedat API, you don't need to worry about the costs associated to uploading/hosting data to decentralized storage. ### What's Arweave? [Arweave](https://www.arweave.org/) is a decentralized storage network designed to provide permanent and low-cost storage for data. Unlike traditional storage systems, where data is often stored in centralized servers that can be subject to censorship or failure, Arweave uses a distributed network of nodes to store data permanently. Arweave uses a unique blockchain-based consensus algorithm called "Proof of Access" to ensure that data remains available and secure on the network. This algorithm incentivizes users to store data on the network by rewarding them with a cryptocurrency called "AR," which can be used to pay for storage fees or exchanged for other cryptocurrencies or fiat currencies. Overall, Arweave provides a secure, decentralized, and cost-effective way to store data for the long term. ### What's Filecoin? [Filecoin](https://docs.filecoin.io/) is a decentralized storage network that allows users to store, retrieve, and share data securely and reliably. It uses a blockchain-based system to create a decentralized marketplace where users can buy and sell storage space, allowing them to store their data on a network of computers around the world. Filecoin's unique feature is its use of a Proof of Replication and Proof of Space-Time consensus algorithm. This ensures that storage providers are actually storing the data they claim to be storing, and that the data is being stored securely and reliably. In return for providing storage space, storage providers receive Filecoin tokens, which they can use to purchase additional storage space, trade on exchanges, or convert into other cryptocurrencies or fiat currencies. Overall, Filecoin provides a secure, decentralized, and cost-effective way to store and share data, without relying on centralized servers or storage providers. # Getting started This page will help you get started using the Storedat API {% hint style="warning" %} Please note that the Storedat API is currently in Beta and at this time it is not recommended to be used in a production environment {% endhint %} ### Get your API key Certain queries are only accessible via an API key and client-id (see the [Basics section ](/reference/api-reference/basics)in the API Reference) but there are those that can be used without credentials (See [Public API Access](/reference/api-reference/basics#public-api-access)). Any request through a API Key gated endpoint that doesn't include the necessary credentials will return an error. ### How to sign up for the Beta Program? Sign ups are currently closed ### Explore the playground Take a tour of the GraphQL playground by visiting the following URL: [`https://perma.storedat.io/api/v1/graphql`](https://perma.storedat.io/api/v1/graphql) ### Want to start playing around? Please see the [client integration section](/integrating-a-client) for how to get up and running ASAP with a convenient starter template for you to fork and play around with ### Found an issue? If you've stumbled onto a bug, please fill out the following issue report: [Report an Issue](https://docs.google.com/forms/d/e/1FAIpQLSeIyKKHAzqWwSce5svez6NiYVhwzDKyTqbloR-SfY73Kt5usA/viewform) ### Have a feature request? If you have a feature request, we'd love to hear it! Please use the following form to let us know what you had in mind: [Feature Request form](https://docs.google.com/forms/d/e/1FAIpQLSfnV5Szu8BTukrcbtmT0T9VTKN6EiL99scOgbSY99rkEKsV9A/viewform) # Integrating a client Use the storedat-api-starter-template to get up and running quickly Please pull/fork the following NextJS and apollo-client starter template to quickely get up and running with the Storedat API: # API Reference This section will provide a reference around the Storedat API Dive into the specifics of each API method by checking out our complete API documentation. We recommend starting with the [Basics](/reference/api-reference/basics) # Basics This page will give you the necessary information needed to use the Storedat API ### Endpoint URL Please use the following endpoint to communicate with the API [`https://perma.storedat.io/api/v1/graphql`](https://perma.storedat.io/api/v1/graphql) ### Public API Access The following methods are available to the public for use without the need of an API Key (subject to [rate limits](#rate-limits)) * [GetGlossaryTerm](/reference/api-reference/query/getglossaryterm) * [GetDataFromArweave](/reference/api-reference/query/getdatafromarweave) * [GetDataFromFilecoin](/reference/api-reference/query/getdatafromfilecoin) ### API Key protected Access While there is a set of public endpoints available for use as mentioned in the above section, the Storedat API requires that you have the following two headers for the [GetData](/reference/api-reference/query/getdata) method (also subject to [rate limits](#rate-limits)) | Header | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `client-id` | A identifier representing you as a user of the API. This will be provided to you upon signing up for the beta program | | `Authorization` | Your API Key required to be able to interact with the service. This will be provided to you upon signing up for the beta program | The following should be passed into every request made to [GetData](/reference/api-reference/query/getdata) and [CreateData](/reference/api-reference/mutation/createdata) ```json { "client-id": "your_client_id", "Authorization": "your_api_key" } ``` Failure to do so or providing invalid credentials will lead to an error response from the server ### Rate limits There are rate limits in place on the Stordat API to ensure fair use and to help avoid malicious attempts to bring down the service. Those rates are as follows: | Operation | Rate limit | | --------- | -------------------------------------------------------------- | | Query | 50 calls per minute cumulative of all read oriented operations | These rate limits are subject to change but will be reflected in this documentation if a change does occur # Query This series of subpages will go over the query level operations available through the Storedat API * [GetGlossaryTerm](/reference/api-reference/query/getglossaryterm) * [GetDataFromArweave](/reference/api-reference/query/getdatafromarweave) * [GetDataFromFilecoin](/reference/api-reference/query/getdatafromfilecoin) * [GetData](/reference/api-reference/query/getdata) # GetGlossaryTerm Get a web3 glossary term definition ## Description This query will return a glossary definition of a term that's held in the [Glosseta](https://glosseta.com) web3 glossary ### Arguments | Input | Description | | -------- | ------------------------------------------------------------------------ | | `term` | The term you're searching for | | `locale` | The locale you wish to have the definition returned. Default is english | ### Response Details | Detail | Description | | ------------ | -------------------------------------------------------------------------------------- | | `term` | The name of the searched glossary term | | `category` | The category that the term falls under (i.e. general, protocol, application, etc...) | | `definition` | The definition of the term in the locale that was specified in the request | | `providerId` | The provider specific identifier to locate the data on decentralized storage providers | ### Sample Query ```graphql query { GetGlossaryTerm(term: "web3", locale: EN) { definition category term providerId } } ``` ### Sample Response ```json { "data": { "GetGlossaryTerm": { "definition": "A term that defines the next generation of the web looking to make blockchains the backbone of the internet and introduce the concept of the token economy. The token economy refers to the change of mindset with regards to how wealth, governance, community building and applications will be driven by a programmable means via blockchains.", "category": "general", "term": "web3" "providerId": "t2JjLSaMEAkp9s0Bk8g_9kpwwWVNhiSaEs8ERJHJ-kc" } } } ``` # GetDataFromArweave Get data stored on Arweave ## Description This query will allow one to search arweave directly for data in bulk. It queries both the Arweave GraphQL API and the Arweave Gateway to be able to return data in one call instead of having to first search for the transaction id and then querying the gateway ### Arguments | Input | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `targetWalletAddress` | The target wallet address the data belongs to | | `metadata` | An array of key/value pairs representing tags in the Arweave ecosystem allowing one to filter a search | | `sort` |

Used to specify a sort order by block inclusion time.

Defaults to descending order

| | `limit` |

The number of results to return: Minimum is 1 and maximum is 10

Note: The maximum limit will look to be expanded in the future

| ### Response Details
DetailDescription
providerIdThe transaction id pertaining to the asset retrieved
dataThe stored data represented as a string

In the case of the data being JSON, TEXT or HTML the data will be returned as a string. In all other cases, the data will be returned as a url pointing to the asset
urlThe url pointing to the asset on the Arweave gateway
metadataAn array of key/value pairs representing tags
providerThe web3 storage solution the data is stored. In this case, ARWEAVE
creationTimestampThe block creation timestamp of the data
### Sample Query ```graphql query { GetDataFromArweave( targetWalletAddress: "FWh7-V_t6BHFNwoTLpQOj3w62TxXE7teHW9opgrCMqE" metadata: [{ name: "category", value: "general" }] sort: ASC limit: 3 ) { providerId provider data url metadata { name value } creationTimestamp } } ``` ### Sample Response ```json { "data": { "GetDataFromArweave": [ { "providerId": "-Hs6t54QWPBi8ICvnQlArymBt03oOdsdBNpYqPgb6CE", "provider": "ARWEAVE", "data": "{\"Content-Type\":\"application/json\",\"term\":\"whale\",\"description\":\"A term for an individual holding a large amount of cryptocurrency.\",\"locale\":\"en\",\"source\":\"GLOSSETA\",\"category\":\"general\"}", "url": "https://www.arweave.net/-Hs6t54QWPBi8ICvnQlArymBt03oOdsdBNpYqPgb6CE", "metadata": [ { "name": "Content-Type", "value": "application/json" }, { "name": "term", "value": "whale" }, { "name": "description", "value": "A term for an individual holding a large amount of cryptocurrency." }, { "name": "locale", "value": "en" }, { "name": "source", "value": "GLOSSETA" }, { "name": "category", "value": "general" } ], "creationTimestamp": "2021-10-24T05:08:07+00:00" }, { "providerId": "rEgp75_wUWe-B-wsfsWIZqjxPRsnJlDOuWU9Qh-2qzc", "provider": "ARWEAVE", "data": "{\"Content-Type\":\"application/json\",\"term\":\"hodl\",\"description\":\"An acronym for hold on for dear life (equivalent to HOLD) often used to encourage people not to sell cryptocurrency impulsively on huge swings in price.\",\"locale\":\"en\",\"source\":\"GLOSSETA\",\"category\":\"general\"}", "url": "https://www.arweave.net/rEgp75_wUWe-B-wsfsWIZqjxPRsnJlDOuWU9Qh-2qzc", "metadata": [ { "name": "Content-Type", "value": "application/json" }, { "name": "term", "value": "hodl" }, { "name": "description", "value": "An acronym for hold on for dear life (equivalent to HOLD) often used to encourage people not to sell cryptocurrency impulsively on huge swings in price." }, { "name": "locale", "value": "en" }, { "name": "source", "value": "GLOSSETA" }, { "name": "category", "value": "general" } ], "creationTimestamp": "2021-10-24T05:08:07+00:00" }, { "providerId": "rJV_2_Lp3sMZPjjNW6LAbiowSk0MDQRPadJ33JTPwrw", "provider": "ARWEAVE", "data": "{\"Content-Type\":\"application/json\",\"term\":\"blockchain\",\"description\":\"A publicly-accessible digital ledger used to store and transfer information without the need for a central authority. Blockchains are the core technology on which cryptocurrency protocols like Bitcoin and Ethereum are built.\",\"locale\":\"en\",\"source\":\"GLOSSETA\",\"category\":\"general\"}", "url": "https://www.arweave.net/rJV_2_Lp3sMZPjjNW6LAbiowSk0MDQRPadJ33JTPwrw", "metadata": [ { "name": "Content-Type", "value": "application/json" }, { "name": "term", "value": "blockchain" }, { "name": "description", "value": "A publicly-accessible digital ledger used to store and transfer information without the need for a central authority. Blockchains are the core technology on which cryptocurrency protocols like Bitcoin and Ethereum are built." }, { "name": "locale", "value": "en" }, { "name": "source", "value": "GLOSSETA" }, { "name": "category", "value": "general" } ], "creationTimestamp": "2021-10-24T05:08:07+00:00" } ] } } ``` # GetDataFromFilecoin Get data stored on Filecoin ## Description This query will allow one to search Filecoin directly for data ### Arguments | Input | Description | | ----- | ----------------------------------------------- | | `cid` | The content addressable identifier of the asset | ### Response Details {% hint style="info" %} Note that if the CID you passed as an argument is pointing to an archive of data, all individual files will be returned in the response {% endhint %} | Detail | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `providerId` | The `cid` pertaining to the asset retrieved | | `data` |

The stored data represented as a string

In the case of the data being JSON, TEXT or HTML the data will be returned as a string. In all other cases, the data will be returned as a url pointing to the asset

| | `url` | The url pointing to the asset on the Filecoin gateway. | | `provider` | The web3 storage solution the data is stored. In this case, `FILECOIN` | | `creationTimestamp` | The creation timestamp of the data | ### Sample Query ```graphql query { GetDataFromFilecoin(cid: "bafybeigom7fivisf3c43btyn6foza2ciavlsjqlh5hd3uguc56we7hujaa") { providerId url data metadata { name value } provider creationTimestamp } } ``` ### Sample Response ```json { "data": { "GetDataFromFilecoin": [ { "providerId": "bafkreiem2a3z5udj53fgob3iogusxi3h6nptnbvqwnc7vfwtd25navhvhu", "url": "https://gateway.ipfs.io/ipfs/bafkreiem2a3z5udj53fgob3iogusxi3h6nptnbvqwnc7vfwtd25navhvhu/test-upload.json", "data": "{\n\"image\": \"https://moonrunners.herokuapp.com/api/7_7 - Waning Crescent Moon/image\",\n\"name\": \"Moonrunners #7\",\n\"description\": \"A collection of 10,000 PFPs. Free mint. No discord. No roadmap. CCO. Protect the Moonrunners at all costs.\",\n\"attributes\": [\n{\n\"trait_type\": \"Background\",\n\"value\": \"Pink\"\n},\n{\n\"trait_type\": \"Body\",\n\"value\": \"Brave\"\n},\n{\n\"trait_type\": \"Fur\",\n\"value\": \"Green\"\n},\n{\n\"trait_type\": \"Outerwear\",\n\"value\": \"Gold Chain\"\n},\n{\n\"trait_type\": \"Mouth\",\n\"value\": \"Dribble\"\n},\n{\n\"trait_type\": \"Eyes\",\n\"value\": \"Angry Grey\"\n},\n{\n\"trait_type\": \"Headwear\",\n\"value\": \"Eagle\"\n},\n{\n\"trait_type\": \"Moon Cycle\",\n\"value\": \"Default Moon Cycle\"\n}\n],\n\"dna\": \"0c622ed13d00fe79a2345abbd9fa09185a68cc1a\"\n}\n", "metadata": [], "provider": "FILECOIN", "creationTimestamp": "2022-11-30T04:30:48Z" } ] } } ``` # GetData Get Data from a supported web3 storage provider Description Search the Storedat API directly for data. The difference between this method and the provider specific query methods is that this queries the Storedat API indexing system. Only data uploaded through the [CreateData](/reference/api-reference/mutation/createdata) method will be available to retrieve through this endpoint. Data previously or externally uploaded should be queried through the provider specific methods outlined prior in this section. ### Arguments | Input | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `groupId` | The unique grouping id identifying the data you use to store your data. You can use this to group related data that you want to store together (i.e. NFT project metadata, content to a given entity). Should only include alphanumerical characters and the `-` character | | `metadata` | An array of key/value pairs representing the metadata of your data | | `sort` | Used to specify a sort order by block inclusion time. | | `limit` |

Optional field to specify the number of results to be returned.

If omitted, all results under the given groupId will be returned

| ### Response Details | Detail | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `providerId` | The identifier of the content provided by the underlying storage protocol i.e transactionID, CID | | `data` |

String representation of the data

Note: Data of the types listed below will be return as a string:

All other MIME types will have data returned as the url pointing to that content on the underlying storage protocol

| | `url` | The url pointing to the content hosted on the underlying storage protocol | | `provider` | The web3 storage solution the data is stored. | | `metadata` | An array of key/value pairs representing the metadata of your data | | `creationTimestamp` | The time of creation of your data | | `errorMessage` | An error message if an issue occurs while mutating your data | ### Request Headers | Header | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `client-id` | An identifier representing you as a user of the API. This will be provided to you upon signing up for the beta program | | `Authorization` | Your API Key required to be able to interact with this method. This will be provided to you upon signing up for the beta program | ### Sample Query ```graphql query { GetData( groupId: "your-group-id-here", sort: DESC, limit: 1 ) { data providerId url creationTimestamp metadata { name value } provider } } ``` ### Sample Response ```json { "data": { "GetData": [ { "data": "{'perma': 'storedat'}", "providerId": "0pyv5KdH0MV1IhxXFRq7oiQkglslEIH1NrpNcFdAbv4", "url": "https://www.arweave.net/0pyv5KdH0MV1IhxXFRq7oiQkglslEIH1NrpNcFdAbv4", "creationTimestamp": "2022-12-09T05:54:22.575141+00:00", "metadata": [ { "name": "key1", "value": "value1" }, { "name": "key2", "value": "value2" } ], "provider": "ARWEAVE" } ] } } ```