openapi: 3.0.3
info:
  version: 1.0.0
  title: Web application API definition
servers:
  - url: https://api.knotcity.io/api
    description: Production environment.
  - url: https://staging.api.knotcity.io/api
    description: Staging environment.
paths:
  /webapp/emails/change:
    get:
      summary: Check email change
      description: Check email change token and retrieve email change data.
      operationId: ApplicationEmailsChange
      tags:
        - Emails
      security: []
      parameters:
        - in: query
          name: token
          description: The token given in the email change link.
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/EmailChangeData'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorParameters'
        '401':
          description: Access to this resource was denied as the user needs to update its account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInvalidToken'
        '500':
          description: Access to this resource failed due to an error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorDatabaseConnection'
                  - $ref: '#/components/schemas/ErrorDatabase'
  /webapp/emails/change/confirm:
    post:
      summary: Confirm email change
      description: Change the user's email by the new specified one.
      operationId: ApplicationEmailsConfirmChange
      tags:
        - Emails
      security: []
      requestBody:
        description: Info to authenticate the email change.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmEmailChangeParams'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeSuccess'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorParameters'
                  - $ref: '#/components/schemas/CodeEmailAlreadyUsed'
                  - $ref: '#/components/schemas/CodeInvalidEmail'
                  - $ref: '#/components/schemas/CodeEmailAlreadyChanged'
        '401':
          description: Access to this resource was denied as the user needs to update its account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInvalidToken'
        '410':
          description: Access to this resource was denied as something is no longer present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeAccountDeleted'
        '500':
          description: Access to this resource failed due to an error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorPayment'
                  - $ref: '#/components/schemas/ErrorDatabaseConnection'
                  - $ref: '#/components/schemas/ErrorDatabase'
  /webapp/emails/confirm:
    post:
      summary: Confirm email
      description: Confirm the email of the user using the validation token.
      operationId: ApplicationEmailsConfirm
      tags:
        - Emails
      security: []
      requestBody:
        description: Info to authenticate the email conformation.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmEmailParams'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeSuccess'
                  - $ref: '#/components/schemas/ConfirmEmail'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInvalidToken'
        '500':
          description: Access to this resource failed due to an error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorDatabaseConnection'
                  - $ref: '#/components/schemas/ErrorDatabase'
  /webapp/users/complete-registration:
    get:
      summary: Get complete registration token info
      description: Check the token validity and get the associated info.
      operationId: WebappUsersGetCompleteRegistration
      tags:
        - Users
      security: []
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            minLength: 10
            maxLength: 10
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/CompleteRegistrationInfo'
                    required:
                      - data
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorParameters'
                  - $ref: '#/components/schemas/CodeRegistrationAlreadyCompleted'
        '401':
          description: Access to this resource was denied as the user needs to update its account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInvalidToken'
        '500':
          description: Access to this resource failed due to an error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorDatabaseConnection'
                  - $ref: '#/components/schemas/ErrorDatabase'
    put:
      summary: Complete registration
      description: Complete the registration of an account created by someone else on the dashboard.
      operationId: WebappUsersPutCompleteRegistration
      tags:
        - Users
      security: []
      requestBody:
        description: Info about the user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteRegistrationParams'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AppLinks'
                    required:
                      - data
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorParameters'
                  - $ref: '#/components/schemas/CodeRegistrationAlreadyCompleted'
        '401':
          description: Access to this resource was denied as the user needs to update its account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInvalidToken'
        '500':
          description: Access to this resource failed due to an error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorDatabaseConnection'
                  - $ref: '#/components/schemas/ErrorDatabase'
  /webapp/users/password/reset:
    get:
      summary: Get reset password token info
      description: Check the token validity and get the associated info.
      operationId: WebappUsersGetPasswordReset
      tags:
        - Users
      security: []
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            minLength: 10
            maxLength: 10
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CodeSuccess'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PasswordResetInfo'
                    required:
                      - data
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorParameters'
                  - $ref: '#/components/schemas/CodeAccountDoNotHavePassword'
        '401':
          description: Access to this resource was denied as the user needs to update its account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInvalidToken'
        '500':
          description: Access to this resource failed due to an error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorDatabaseConnection'
                  - $ref: '#/components/schemas/ErrorDatabase'
    put:
      summary: Reset password
      description: Reset the password to the new specified one.
      operationId: WebappUsersPutPasswordReset
      tags:
        - Users
      security: []
      requestBody:
        description: The new password.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetParams'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeSuccess'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorParameters'
                  - $ref: '#/components/schemas/CodeAccountDoNotHavePassword'
        '401':
          description: Access to this resource was denied as the user needs to update its account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeInvalidToken'
        '410':
          description: Access to this resource was denied as something is no longer present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeAccountDeleted'
        '500':
          description: Access to this resource failed due to an error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorDatabaseConnection'
                  - $ref: '#/components/schemas/ErrorDatabase'
components:
  schemas:
    CodeSuccess:
      description: Request successful.
      type: object
      properties:
        code:
          description: Success.
          type: integer
          enum:
            - 0
      required:
        - code
    EmailChangeData:
      type: object
      properties:
        email:
          description: Current email of the account.
          type: string
          format: email
        new_email:
          description: New email to which the change must be validated.
          type: string
          format: email
        current_organization_name:
          description: Current organization of the user. Changing the email will make it leave the organization. Null if the user doesn't have an organization.
          type: string
          minLength: 1
          nullable: true
        new_organization_name:
          description: Organization matching the new requested email. User will join it if it confirm the email change.
          type: string
          minLength: 1
          nullable: true
        label_name:
          description: The application white label of the user.
          type: string
          minLength: 1
          maxLength: 20
      required:
        - email
        - new_email
        - current_organization_name
        - new_organization_name
        - label_name
    ErrorParameters:
      type: object
      properties:
        code:
          description: Given parameter are not valid.
          type: integer
          minimum: -39999999
          maximum: -30000000
        message:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - code
        - message
    CodeInvalidToken:
      type: object
      properties:
        code:
          description: The given token is not valid.
          type: integer
          enum:
            - 106
      required:
        - code
    ErrorDatabaseConnection:
      type: object
      properties:
        code:
          description: An error occurred while trying to contact our database.
          type: integer
          minimum: -59999999
          maximum: -50000000
      required:
        - code
    ErrorDatabase:
      type: object
      properties:
        code:
          description: An error occurred while interacting with our database.
          type: integer
          minimum: -69999999
          maximum: -60000000
      required:
        - code
    ConfirmEmailChangeParams:
      type: object
      properties:
        email_token:
          description: The mail change token.
          type: string
          minLength: 10
          maxLength: 10
        email:
          description: The new email address.
          type: string
          format: email
      required:
        - email_token
        - email
    CodeEmailAlreadyUsed:
      type: object
      properties:
        code:
          description: The given email is already used by another user.
          type: integer
          enum:
            - 1
      required:
        - code
    CodeInvalidEmail:
      type: object
      properties:
        code:
          description: The given email is not valid.
          type: integer
          enum:
            - 9
      required:
        - code
    CodeEmailAlreadyChanged:
      type: object
      properties:
        code:
          description: User email was already changed to this one.
          type: integer
          enum:
            - 28
      required:
        - code
    CodeAccountDeleted:
      type: object
      properties:
        code:
          description: The user account was deleted.
          type: integer
          enum:
            - 47
      required:
        - code
    ErrorPayment:
      type: object
      properties:
        code:
          description: An error occurred with our payment provider.
          type: integer
          minimum: -89999999
          maximum: -80000000
      required:
        - code
    ConfirmEmailParams:
      type: object
      properties:
        token:
          description: The mail change token.
          type: string
          minLength: 10
          maxLength: 10
      required:
        - token
    ConfirmEmail:
      type: object
      properties:
        label_name:
          description: The name of the app label.
          type: string
          minLength: 1
        email:
          description: The confirmed email address.
          type: string
          format: email
        android_store_url:
          description: Google Play url of the app.
          type: string
          format: url
          nullable: true
        ios_store_url:
          description: Apple store url of the app.
          type: string
          format: url
          nullable: true
      required:
        - label_name
        - email
        - android_store_url
        - ios_store_url
    CompleteRegistrationInfo:
      type: object
      properties:
        email:
          description: The email address of the user.
          type: string
          format: email
        firstname:
          description: The user's first name.
          type: string
          maxLength: 50
        label_name:
          description: The app label name the user is registered on.
          type: string
        app_label_term_url:
          description: The URL to the app label terms of use.
          type: string
          format: url
        network_term_url:
          description: The URL to the network terms of use.
          type: string
          format: url
          nullable: true
      required:
        - email
        - firstname
        - label_name
        - app_label_term_url
        - network_term_url
    CodeRegistrationAlreadyCompleted:
      type: object
      properties:
        code:
          description: The user registration is already completed.
          type: integer
          enum:
            - 266
      required:
        - code
    CompleteRegistrationParams:
      type: object
      properties:
        token:
          description: The complete registration token.
          type: string
          minLength: 10
          maxLength: 10
        password:
          description: The user's password.
          type: string
          minLength: 8
          maxLength: 255
        consents:
          description: The user's consents.
          type: object
          properties:
            emails.networkstatus:
              type: boolean
              nullable: true
            emails.promotional:
              type: boolean
              nullable: true
        trip_retention_in_months:
          description: The trip retention in months. Null means forever, if not provided, defaults to null.
          type: integer
          minimum: 3
          maximum: 24
          nullable: true
      required:
        - token
        - password
    AppLinks:
      type: object
      properties:
        android_store_url:
          description: The Android app store URL.
          type: string
          format: url
          nullable: true
        ios_app_store_url:
          description: The iOS app store URL.
          type: string
          format: url
          nullable: true
      required:
        - android_store_url
        - ios_app_store_url
    PasswordResetInfo:
      type: object
      properties:
        email:
          description: The email address of the user.
          type: string
          format: email
        label_name:
          description: The app label name the user is registered on.
          type: string
      required:
        - email
        - label_name
    CodeAccountDoNotHavePassword:
      type: object
      properties:
        code:
          description: The given account cannot be authenticated using an email and a password.
          type: integer
          enum:
            - 48
      required:
        - code
    PasswordResetParams:
      type: object
      properties:
        password_token:
          description: The change password token.
          type: string
          minLength: 10
          maxLength: 10
        password:
          description: The user's password.
          type: string
          minLength: 8
          maxLength: 255
      required:
        - password_token
        - password
