api_v1.yml

openapi: 3.1.0

info:
  title: hdrop API v1
  description: Full specification for the hdrop API v1.
  version: 1.0.0

servers:
  - url: https://api.hdrop.io/v1
    description: The official hdrop server
  - url: https://api-staging.hdrop.io/v1
    description: The official hdrop staging server

tags:
  - name: files
    description: File operations
  - name: challenge
    description: Challenges are used to unambiguously verify that a user has access to a specific file.

paths:
  /files:
    post:
      summary: Upload a file
      tags:
        - files
      operationId: uploadFile
      security: []
      requestBody:
        $ref: '#/components/requestBodies/UploadFile'
      responses:
        '201':
          description: File uploaded
          $ref: "#/components/responses/UploadFile"
        '4xx':
          description: Client error
          $ref: "#/components/responses/Error"
        '5xx':
          description: Server error
          $ref: "#/components/responses/Error"

  /files/{access_token}:
    get:
      summary: Access a file
      tags:
        - files
      operationId: accessFile
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AccessToken'
      responses:
        '200':
          description: File details
          $ref: "#/components/responses/AccessFile"
        '4xx':
          description: Client error
          $ref: "#/components/responses/Error"
        '5xx':
          description: Server error
          $ref: "#/components/responses/Error"
    delete:
      summary: Delete a file
      tags:
        - files
      operationId: deleteFile
      security: []
      parameters:
        - $ref: "#/components/parameters/AccessToken"
        - $ref: "#/components/parameters/UpdateToken"
      responses:
        '200':
          description: File deleted
          $ref: "#/components/responses/Success"
        '4xx':
          description: Client error
          $ref: "#/components/responses/Error"
        '5xx':
          description: Server error
          $ref: "#/components/responses/Error"

  /files/{access_token}/expiry:
    post:
      summary: Set file expiry
      tags:
        - files
      operationId: setFileExpiry
      security: []
      parameters:
        - $ref: "#/components/parameters/AccessToken"
        - $ref: "#/components/parameters/UpdateToken"
      requestBody:
        $ref: "#/components/requestBodies/SetFileExpiry"
      responses:
        '200':
          description: File expiry set
          $ref: "#/components/responses/Success"
        '4xx':
          description: Client error
          $ref: "#/components/responses/Error"
        '5xx':
          description: Server error
          $ref: "#/components/responses/Error"

  /files/{access_token}/challenge:
    get:
      summary: Get a challenge
      tags:
        - challenge
      operationId: getChallenge
      security: []
      parameters:
        - $ref: '#/components/parameters/AccessToken'
      responses:
        '200':
          description: Challenge obtained
          $ref: "#/components/responses/GetChallenge"
        '4xx':
          description: Client error
          $ref: "#/components/responses/Error"
        '5xx':
          description: Server error
          $ref: "#/components/responses/Error"
    post:
      summary: Submit a challenge
      tags:
        - challenge
      operationId: submitChallenge
      security: []
      parameters:
        - $ref: '#/components/parameters/AccessToken'
      requestBody:
        $ref: "#/components/requestBodies/SubmitChallenge"
      responses:
        '200':
          description: Challenge result
          $ref: "#/components/responses/SubmitChallenge"
        '4xx':
          description: Client error
          $ref: "#/components/responses/Error"
        '5xx':
          description: Server error
          $ref: "#/components/responses/Error"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  parameters:
    AccessToken:
      required: true
      name: access_token
      in: path
      description: Access token for the file
      schema:
        type: string
    UpdateToken:
      required: true
      name: update_token
      in: query
      description: Update token for the file
      schema:
        type: string
  requestBodies:
    UploadFile:
      required: true
      description: Upload a file
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              iv:
                type: string
                format: base64
              salt:
                type: string
                format: base64
              file_data:
                type: string
                format: binary
              file_name_data:
                type: string
                format: base64
              challenge_data:
                type: string
                format: base64
              challenge_hash:
                type: string
    SetFileExpiry:
      required: true
      description: Set file expiry
      content:
        application/json:
          schema:
            type: object
            properties:
              expiry:
                description: Expiry time in seconds
                type: number
    SubmitChallenge:
      required: true
      description: Submit a challenge
      content:
        application/json:
          schema:
            type: object
            properties:
              challenge:
                type: string
  responses:
    Error:
      description: Common error response
      content:
        application/json:
          schema:
            type: object
            properties:
              reason:
                type: string
    Success:
      description: Common success response
      content:
        application/json:
          schema:
            type: object
    UploadFile:
      description: File uploaded
      content:
        application/json:
          schema:
            type: object
            properties:
              access_token:
                type: string
              update_token:
                type: string
    GetChallenge:
      description: Challenge obtained
      content:
        application/json:
          schema:
            type: object
            properties:
              salt:
                type: string
                format: base64
              iv:
                type: string
                format: base64
              challenge:
                type: string
                format: base64
    SubmitChallenge:
      description: Challenge result
      content:
        application/json:
          schema:
            type: object
            properties:
              file_name_data:
                description: Encrypted file name
                type: string
                format: base64
    AccessFile:
      description: File details
      content:
        application/json:
          schema:
            type: object
            properties:
              file_url:
                description: Direct download URL for the file
                type: string
        application/octet-stream:
          schema:
            type: string
            format: binary