Unlock Protocol Metadata API

openapi: 3.0.0
info:
  title: Unlock Locksmith Applications Metadata API
  version: '2'
  description: Locksmith provides backend functionality for enabling ticketing, metadata storage, and notification hooks.
  license:
    name: MIT
servers:
- url: https://locksmith.unlock-protocol.com
  description: Production Server
- url: https://staging-locksmith.unlock-protocol.com
  description: Staging Server
tags:
- name: Metadata
paths:
  /v2/api/metadata/{network}/locks/{lockAddress}:
    get:
      operationId: lockMetadata
      description: Get metadata for lock address.
      parameters:
      - $ref: '#/components/parameters/Network'
      - $ref: '#/components/parameters/LockAddress'
      responses:
        200:
          description: JSON metadata containing name, description, and custom properties for lock.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true
        404:
          $ref: '#/components/responses/404.NotFound'
        500:
          $ref: '#/components/responses/500.InternalError'
      tags:
      - Metadata
    put:
      operationId: updateLockMetadata
      security:
      - User:
        - lockManager
      description: Update or create metadata for lock address.
      parameters:
      - $ref: '#/components/parameters/Network'
      - $ref: '#/components/parameters/LockAddress'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: JSON metadata inside metadata field will be saved.
              type: object
              nullable: false
              properties:
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        201:
          description: JSON metadata containing name, description, and custom properties for lock address.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true
        204:
          description: JSON metadata containing name, description, and custom properties for lock address.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true
        404:
          $ref: '#/components/responses/404.NotFound'
        500:
          $ref: '#/components/responses/500.InternalError'
      tags:
      - Metadata
  /v2/api/metadata/{network}/locks/{lockAddress}/keys/{keyId}:
    get:
      operationId: keyMetadata
      security:
      - User: []
      - {}
      parameters:
      - $ref: '#/components/parameters/Network'
      - $ref: '#/components/parameters/LockAddress'
      - $ref: '#/components/parameters/KeyId'
      description: Get key and user metadata.
      responses:
        200:
          description: JSON metadata containing name, description, custom properties and user metadata if authenticated for a key.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                properties:
                  keyId:
                    type: string
                    nullable: false
                  lockAddress:
                    type: string
                    nullable: false
                  network:
                    type: integer
                    nullable: false
                additionalProperties: true
      tags:
      - Metadata
    put:
      operationId: updateKeyMetadata
      security:
      - User:
        - lockManager
      description: Update or create metadata for key.
      parameters:
      - $ref: '#/components/parameters/Network'
      - $ref: '#/components/parameters/LockAddress'
      - $ref: '#/components/parameters/KeyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: JSON metadata inside metadata field will be saved.
              type: object
              nullable: false
              properties:
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        201:
          description: JSON metadata containing name, description, and custom properties for key.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'
        404:
          $ref: '#/components/responses/404.NotFound'
        500:
          $ref: '#/components/responses/500.InternalError'
      tags:
      - Metadata
  /v2/api/metadata/{network}/locks/{lockAddress}/users/{userAddress}:
    put:
      operationId: updateUserMetadata
      security:
      - User:
        - user
        - lockManager
      description: Update or create user metadata for lock.
      parameters:
      - $ref: '#/components/parameters/Network'
      - $ref: '#/components/parameters/LockAddress'
      - $ref: '#/components/parameters/UserAddress'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: '#/components/schemas/UserMetadataInput'
      responses:
        204:
          description: Return user metadata saved.
          content:
            application/json:
              schema:
                type: object
                nullable: false
                additionalProperties: true
        400:
          $ref: '#/components/responses/400.Invalid'
        401:
          $ref: '#/components/responses/401.NotAuthenticated'
        404:
          $ref: '#/components/responses/404.NotFound'
        409:
          $ref: '#/components/responses/409.Conflict'
        500:
          $ref: '#/components/responses/500.InternalError'
      tags:
      - Metadata
    get:
      operationId: getUserMetadata
      security:
      - User:
        - user
      description: get user metadata for a lock.
      parameters:
      - $ref: '#/components/parameters/LockAddress'
      - $ref: '#/components/parameters/UserAddress'
      responses:
        200:
          description: Returns user metadata if authenticated for a lock.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMetadata'
        401:
          $ref: '#/components/responses/401.NotAuthenticated'
        404:
          $ref: '#/components/responses/404.NotFound'
        500:
          $ref: '#/components/responses/500.InternalError'
      tags:
      - Metadata
  /v2/api/metadata/users:
    put:
      operationId: updateUsersMetadata
      security:
      - User: []
      - {}
      description: Update or create user metadata for lock.
      requestBody:
        required: true
        description: users array containing user metadata.
        content:
          application/json:
            schema:
              type: object
              nullable: false
              properties:
                users:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserMetadata'
      responses:
        201:
          description: Array containing user metadata which was created. If the user already has metadata, it will not be updated and present in the array.
          content:
            application/json:
              schema:
                type: object
                nullable: false
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserMetadata'
                  error:
                    description: Array containing user addresses for which metadata was not created.
                    type: array
                    items:
                      type: string
        400:
          $ref: '#/components/responses/400.Invalid'
        404:
          $ref: '#/components/responses/404.NotFound'
        500:
          $ref: '#/components/responses/500.InternalError'
      tags:
      - Metadata
components:
  schemas:
    GenericInvalidBodyError:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: Response body schema is invalid.
          nullable: false
        error:
          type: string
          nullable: true
    GenericServerError:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: There was an error in fullfiling the request.
          nullable: false
    UserMetadata:
      type: object
      nullable: false
      required:
      - lockAddress
      - userAddress
      - metadata
      - network
      properties:
        network:
          type: integer
          nullable: false
        lockAddress:
          type: string
          nullable: false
        userAddress:
          type: string
          nullable: false
        metadata:
          $ref: '#/components/schemas/UserMetadataInput'
    NotAuthenticated:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: You are not authorized or authenticated to perform this action.
          nullable: false
    UserMetadataInput:
      type: object
      nullable: false
      properties:
        public:
          type: object
          nullable: true
          default: {}
          additionalProperties: true
        protected:
          type: object
          nullable: true
          default: {}
          additionalProperties: true
    GenericNotFound:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: resource not found
          nullable: false
  parameters:
    UserAddress:
      in: path
      name: userAddress
      required: true
      description: User address.
      schema:
        type: string
    Network:
      in: path
      name: network
      required: true
      description: Network id.
      schema:
        type: integer
    LockAddress:
      in: path
      name: lockAddress
      required: true
      description: Lock address.
      schema:
        type: string
    KeyId:
      in: path
      name: keyId
      required: true
      description: Key Id.
      schema:
        type: string
  responses:
    404.NotFound:
      description: The item you are making request for does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericNotFound'
    400.Invalid:
      description: Invalid input received. Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericInvalidBodyError'
    401.NotAuthenticated:
      description: User is not authenticated.
      content:
        application:
          schema:
            $ref: '#/components/schemas/GenericServerError'
    403.NotAuthenticatedOrAuthorized:
      description: User is not authorized to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotAuthenticated'
    409.Conflict:
      description: There is a conflict. The resource already exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericServerError'
    500.InternalError:
      description: Unable to fullfil request due to internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericServerError'
  securitySchemes:
    User:
      type: http
      scheme: bearer
      bearerFormat: JWT
    Application:
      type: apiKey
      name: api-key
      in: query