# /api/v3/storages
---
get:
  summary: Get Storages
  operationId: list_storages
  tags:
    - File links
  description: Returns a collection of storages.
  responses:
    '200':
      description: OK
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/storage_collection_model.yml'
          examples:
            'Simple storage collection':
              $ref: '../components/examples/storages-simple-collection-response.yml'
    '400':
      description: Returned if the client sends invalid request parameters e.g. filters
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
            message: Filters Invalid filter does not exist.

post:
  summary: Creates a storage.
  operationId: create_storage
  tags:
    - File links
  description: |-
    Creates a storage resource. When creating a storage, a confidential OAuth 2 provider application is created
    automatically. The oauth client id and secret of the created OAuth application are returned in the response.
    
    **IMPORTANT:** This is the only time, the oauth client secret is visible to the consumer. After that, the secret is
    hidden.
    
    To update the storage with OAuth client credentials, which enable the storage resource to behave as an OAuth 2
    client against an external OAuth 2 provider application, another request must be made to create those, see
    `POST /api/v3/storages/{id}/oauth_client_credentials`.
  requestBody:
    content:
      application/json:
        schema:
          $ref: '../components/schemas/storage_write_model.yml'
  responses:
    '201':
      description: Created
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/storage_read_model.yml'
    '400':
      $ref: '../components/responses/invalid_request_body.yml'
    '403':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
            message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** Depends on the page the grid is defined for.
    '406':
      $ref: '../components/responses/missing_content_type.yml'
    '415':
      $ref: '../components/responses/unsupported_media_type.yml'
    '422':
      description: |-
        Returned if:

        * a constraint for a property was violated (`PropertyConstraintViolation`)
