diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml
index 6752831..52ccabb 100644
--- a/ipfs-pinning-service.yaml
+++ b/ipfs-pinning-service.yaml
@@ -45,6 +45,28 @@ response. The old pin object is deleted automatically.
 
 Pin object can be removed via `DELETE /pins/{cid-of-pin-object}`
 
+# Custom metadata
+
+Pinning Services are encouraged to add support for additional features by
+leveraging optional `meta` attributes:
+
+- `PinStatus.meta[progress]` –  % progress of ongoing pinning operation (if possible to tell)
+
+- `PinStatus.meta[fail_reason]` - service-specific reason why pin operation failed (eg. lack of funds, DAG too big etc)
+
+- `PinStatus.meta[receivers] = ['multiaddr1','multiaddr2']` list of peers to connect to to speed up transfer of pinned data
+
+- `Pin.meta[replication]` – could define how many copies service should keep
+
+- `Pin.meta[providers] = ['multiaddr1','multiaddr2']` list of peers that are known to have pinned data
+
+Those can be vendor-specific, but we encourage community to leverage `meta` to
+come up with conventions that could become part of future revisions of this
+API. 
+
+It is ok to ommit or ignore `meta` attributes.  
+Doing so should not impact the basic pinning functionality.  
+
 # Authorization
 
 An opaque auth token is required to be sent with each request.
@@ -228,12 +250,6 @@ components:
         cid:
           description: CID to be pinned
           type: string
-        depth:
-          description: Defines how deep the DAG should be pinned (-1 recursive, 0 direct)
-          type: integer
-          format: int32
-          default: -1
-          minimum: -1
         meta:
           $ref: '#/components/schemas/Meta'
 
@@ -244,7 +260,7 @@ components:
         - resolving  # pinning in-progress: verifying pin request and looking for providers
         - retrieving # pinning in-progress: connected to at least one provider and fetched at least one block
         - pinned     # pinned successfully
-        - failed     # pining service was unable to finish pinning operation
+        - failed     # pining service was unable to finish pinning operation, details can be found in meta[fail_reason]
         - expired    # (optional) still pinned for some time, but run out of funds and won't be provided to the IPFS network
         - unpinning  # (optional) unpinning in-progress