openapi: 3.0.3
info:
  title: Elemo API
  version: 0.1.0
  description: |
    # Introduction

    The Elemo API allows you to manage users, organizations and other resources within Elemo in a programmatic way. The API is capable of doing all operations that can be executed from the user interface.

    You may use any tool that handles HTTP requests to interact with the API. However, the requests should be made using the HTTPS protocol so that traffic is encrypted.

    You need to obtain an [Access Token](https://en.wikipedia.org/wiki/Access_token) to call most of the API endpoints. The tokens are bound to users, therefore you must have a user in the system as well. Read more about obtaining an access token below.

    ## Requests

    The endpoints have support for the HTTP methods below. Please note that not all endpoints are supporting every HTTP method.

    | Method | Usage                                                                                                                        |
    |----------|------------------------------------------------------------------------------------------------------------------------------|
    | `GET`    | Used to retrieve information about one or many resources.                                                                    |
    | `POST`   | Creates a new resource. The request must include all required attributes.                                                    |
    | `PUT`    | Updates an existing resource. The request must include all required attributes.                                              |
    | `PATCH`  | Partially updates an existing resource. The request attributes are not required. Most of the resources are supporting PATCH. |
    | `DELETE` | Delete a resource from the system. Usually, this is an irreversible action.                                                  |

    ## Authentication

    Authentication is implemented based on the [OAuth 2.0](https://oauth.net/2/) specification supporting the password and authorization code flows. As a rule of thumb, whenever you need to interact with the API use authorization code flow and fallback to password flow if other flows cannot be implemented for any reason.

    After the token obtained, use the token as part of the `Authorization` HTTP header in the format of: `Authorization: Bearer {access_token}`

    ## Pagination

    All endpoints that are returning a list of resources supports and requires pagination. The default page size is `100` items, controlled by the `limit` query parameter. To utilize pagination, you may define `offset` in addition which skips the defined results. Therefore, if `offset` is set to `100`, the endpoint will return the next page's results. Sample request:

    ```shell
    $ curl -H "Authorization: Bearer {access_token}" https://{domain}/api/v1/users?limit=100&offset=100
    ```

    Although the pagination is very flexible, it defines some constraints:

    * The maximum `limit` cannot be greater than `1000`
    * The minimum `limit` cannot be less than `1`
    * The minimum `offset` cannot be less than `0`

    ## Versioning

    ### APIs

    The endpoints are versioned and the version number is part of the path. When the required input or returned output of an endpoint is changed, the current version is being deprecated and a new version of the endpoint is created. Deprecated endpoints are removed when a new major application version is released.

    ### This specification

    In contrast with the APIs, this specification follows semantic versioning.
tags:
  - name: System
    description: System resources.
  - name: Todo
    description: User todo items.
  - name: Organization
    description: Organizations in the system.
  - name: User
    description: Users in the system.
  - name: Permission
    description: Permissions in the system.
servers:
  - url: "https://{domain}/api"
    description: Self-hosted instance.
    variables:
      domain:
        description: domain
        default: example.com
components:
  schemas:
    User:
      title: User
      type: object
      description: A user in the system.
      x-examples:
        example:
          id: 9bsv0s46s6s002p9ltq0
          username: test-user
          first_name: Test
          last_name: User
          email: test.user@example.com
          picture: "https://example.com/users/my-user.png"
          title: Senior Software Engineer
          bio: I'm working smart on software.
          address: Remote
          phone: "+15555551234"
          links:
            - "https://example.com/my-user"
          languages:
            - en
            - hu
          status:
            id: active
          created_at: "2023-01-01T00:00:00Z"
          updated_at: null
      properties:
        id:
          type: string
          description: Unique identifier of the user.
          example: 9bsv0s46s6s002p9ltq0
        username:
          type: string
          description: The unique username of the user.
          pattern: "^[a-z0-9-_]{3,50}$"
          minLength: 3
          maxLength: 50
          example: test-user
        first_name:
          type: string
          description: First name of the user.
          minLength: 1
          maxLength: 50
          example: Test
          nullable: true
        last_name:
          type: string
          description: Last name of the user.
          example: User
          minLength: 1
          maxLength: 50
          nullable: true
        email:
          type: string
          format: email
          example: user@example.com
          minLength: 6
          maxLength: 254
          description: Email address of the user.
        picture:
          type: string
          description: Profile picture of the user.
          format: uri
          example: "https://example.com/users/my-user.png"
          maxLength: 2000
          nullable: true
        title:
          type: string
          description: Work title of the user.
          example: Senior Software Engineer
          minLength: 3
          maxLength: 50
          nullable: true
        bio:
          type: string
          description: Self description of the user.
          maxLength: 500
          example: I'm working smart on software.
          nullable: true
        address:
          type: string
          minLength: 3
          maxLength: 500
          example: Remote
          description: Working address of the user.
          nullable: true
        phone:
          type: string
          example: "+15555551234"
          minLength: 7
          maxLength: 16
          description: Phone number of the user.
          nullable: true
        links:
          type: array
          description: Links to show on profile page.
          uniqueItems: true
          nullable: true
          items:
            type: string
            format: uri
            example: "https://example.com/my-user"
            maxLength: 2000
        languages:
          type: array
          description: Languages of the user.
          uniqueItems: true
          items:
            $ref: "#/components/schemas/Language"
        status:
          $ref: "#/components/schemas/UserStatus"
        created_at:
          type: string
          format: date-time
          description: Date when the user was created.
        updated_at:
          type: string
          format: date-time
          description: Date when the user was updated.
          nullable: true
      required:
        - id
        - username
        - first_name
        - last_name
        - email
        - picture
        - title
        - bio
        - address
        - phone
        - links
        - languages
        - status
        - created_at
        - updated_at
    UserStatus:
      type: string
      enum:
        - active
        - pending
        - inactive
        - deleted
      example: active
      description: Status of the user.
      title: UserStatus
    Organization:
      title: Organization
      type: object
      description: An organization in the system.
      properties:
        id:
          type: string
          description: Unique identifier of the organization.
          example: 9bsv0s46s6s002p9ltq0
        name:
          type: string
          description: Name of the organization.
          maxLength: 120
          example: ACME Inc.
          minLength: 1
        email:
          type: string
          format: email
          example: info@example.com
          minLength: 6
          maxLength: 254
          description: Email address of the organization.
        logo:
          type: string
          description: Logo of the organization.
          format: uri
          example: "https://example.com/static/logo.png"
          maxLength: 2000
          nullable: true
        website:
          type: string
          description: Work title of the user.
          format: uri
          example: "https://example.com"
          maxLength: 2000
          nullable: true
        status:
          $ref: "#/components/schemas/OrganizationStatus"
        members:
          type: array
          description: IDs of the users in the organization.
          uniqueItems: true
          items:
            type: string
            example: 9bsv0s46s6s002p9ltq0
        teams:
          type: array
          description: IDs of the teams in the organization.
          uniqueItems: true
          items:
            type: string
            example: 9bsv0s46s6s002p9ltq0
        namespaces:
          type: array
          description: IDs of the namespaces in the organization.
          uniqueItems: true
          items:
            type: string
            example: 9bsv0s46s6s002p9ltq0
        created_at:
          type: string
          format: date-time
          description: Date when the organization was created.
        updated_at:
          type: string
          format: date-time
          description: Date when the organization was updated.
          nullable: true
      required:
        - id
        - name
        - email
        - logo
        - website
        - status
        - members
        - teams
        - namespaces
        - created_at
        - updated_at
    OrganizationStatus:
      type: string
      enum:
        - active
        - deleted
      example: active
      description: Status of the organization.
      title: OrganizationStatus
    Todo:
      title: Todo
      type: object
      description: A todo item belonging to a user.
      x-examples:
        example:
          id: 9bsv0s46s6s002p9ltq0
          title: Do something great
          description: I'll make the world a better place today.
          priority: normal
          completed: true
          owned_by: string
          created_by: string
          due_date: null
          created_at: "2019-08-24T14:15:22Z"
          updated_at: null
      properties:
        id:
          type: string
          description: Unique identifier of the todo.
          example: 9bsv0s46s6s002p9ltq0
        title:
          type: string
          minLength: 3
          maxLength: 250
          example: Do something great
          description: Title of the todo item.
        description:
          type: string
          minLength: 10
          maxLength: 500
          example: I'll make the world a better place today.
          description: Description of the todo item.
        priority:
          $ref: "#/components/schemas/TodoPriority"
        completed:
          type: boolean
          default: true
          description: Status of the todo item.
        owned_by:
          type: string
          description: ID of the user who owns the todo item.
        created_by:
          type: string
          description: ID of the user who created the todo item.
        due_date:
          type: string
          format: date-time
          description: Completion due date of the todo item.
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Date when the todo item was created.
        updated_at:
          type: string
          format: date-time
          description: Date when the todo item was updated.
          nullable: true
      required:
        - id
        - title
        - description
        - priority
        - completed
        - owned_by
        - created_by
        - due_date
        - created_at
        - updated_at
    TodoPriority:
      type: string
      enum:
        - normal
        - important
        - urgent
        - critical
      example: urgent
      minLength: 6
      maxLength: 9
      description: Priority of the todo item.
    SystemHealth:
      title: SystemHealth
      type: object
      properties:
        cache_database:
          type: string
          enum:
            - healthy
            - unhealthy
            - unknown
          minLength: 7
          maxLength: 9
          description: Health of the cache database.
        graph_database:
          type: string
          enum:
            - healthy
            - unhealthy
            - unknown
          minLength: 7
          maxLength: 9
          description: Health of the graph database.
        relational_database:
          type: string
          enum:
            - healthy
            - unhealthy
            - unknown
          minLength: 7
          maxLength: 9
          description: Health of the relational database.
        license:
          type: string
          enum:
            - healthy
            - unhealthy
            - unknown
          minLength: 7
          maxLength: 9
          description: Health of the license.
        message_queue:
          type: string
          enum:
            - healthy
            - unhealthy
            - unknown
          minLength: 7
          maxLength: 9
          description: Health of the message queue.
      required:
        - cache_database
        - graph_database
        - relational_database
        - license
        - message_queue
      x-examples:
        example:
          cache_database: healthy
          graph_database: healthy
          relational_database: healthy
          license: healthy
          message_queue: healthy
    SystemVersion:
      title: SystemVersion
      type: object
      properties:
        version:
          type: string
          description: Version of the application.
          pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
        commit:
          type: string
          description: Commit hash of the build.
          pattern: "^[0-9a-f]{5,40}$"
        date:
          type: string
          format: date-time
          description: Build date and time of the application.
        go_version:
          type: string
          description: Go version used to build the application.
          pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
      required:
        - version
        - commit
        - date
        - go_version
    SystemLicense:
      title: SystemLicense
      type: object
      properties:
        id:
          type: string
          description: Unique ID identifying the license.
        organization:
          type: string
          description: Name of the organization the license belongs to.
        email:
          type: string
          format: email
          example: info@example.com
          minLength: 6
          maxLength: 254
          description: Email address of the licensee.
        quotas:
          type: object
          description: Quotas available for the license.
          required:
            - documents
            - namespaces
            - organizations
            - projects
            - roles
            - users
          properties:
            documents:
              type: integer
              minimum: 1
              description: Number of documents can exist in the system.
            namespaces:
              type: integer
              minimum: 1
              description: Number of namespaces can exist in the system.
            organizations:
              type: integer
              minimum: 1
              description: Number of organizations active can exist in the system.
            projects:
              type: integer
              minimum: 1
              description: Number of projects can exist in the system.
            roles:
              type: integer
              minimum: 1
              description: Number of roles can exist in the system.
            users:
              type: integer
              minimum: 1
              description: Number of active or pending users can exist in the system.
        features:
          type: array
          uniqueItems: true
          description: Features enabled by the license.
          items:
            type: string
            enum:
              - components
              - custom_statuses
              - custom_fields
              - multiple_assignees
              - releases
        expires_at:
          type: string
          format: date-time
          description: Date and time when the license expires.
      required:
        - id
        - organization
        - email
        - quotas
        - features
        - expires_at
    HTTPError:
      title: HTTPError
      type: object
      properties:
        message:
          type: string
          description: Description of the error.
      required:
        - message
      description: HTTP error description.
    Language:
      type: string
      description: Two-letter ISO language code.
      minLength: 2
      maxLength: 2
      enum:
        - aa
        - ab
        - ae
        - af
        - ak
        - am
        - an
        - ar
        - as
        - av
        - ay
        - az
        - ba
        - be
        - bg
        - bh
        - bi
        - bm
        - bn
        - bo
        - br
        - bs
        - ca
        - ce
        - ch
        - co
        - cr
        - cs
        - cu
        - cv
        - cy
        - da
        - de
        - dv
        - dz
        - ee
        - el
        - en
        - eo
        - es
        - et
        - eu
        - fa
        - ff
        - fi
        - fj
        - fo
        - fr
        - fy
        - ga
        - gd
        - gl
        - gn
        - gu
        - gv
        - ha
        - he
        - hi
        - ho
        - hr
        - ht
        - hu
        - hy
        - hz
        - ia
        - id
        - ie
        - ig
        - ii
        - ik
        - io
        - is
        - it
        - iu
        - ja
        - jv
        - ka
        - kg
        - ki
        - kj
        - kk
        - kl
        - km
        - kn
        - ko
        - kr
        - ks
        - ku
        - kv
        - kw
        - ky
        - la
        - lb
        - lg
        - li
        - ln
        - lo
        - lt
        - lu
        - lv
        - mg
        - mh
        - mi
        - mk
        - ml
        - mn
        - mr
        - ms
        - mt
        - my
        - na
        - nb
        - nd
        - ne
        - ng
        - nl
        - nn
        - "no"
        - nr
        - nv
        - ny
        - oc
        - oj
        - om
        - or
        - os
        - pa
        - pi
        - pl
        - ps
        - pt
        - qu
        - rm
        - rn
        - ro
        - ru
        - rw
        - sa
        - sc
        - sd
        - se
        - sg
        - si
        - sk
        - sl
        - sm
        - sn
        - so
        - sq
        - sr
        - ss
        - st
        - su
        - sv
        - sw
        - ta
        - te
        - tg
        - th
        - ti
        - tk
        - tl
        - tn
        - to
        - tr
        - ts
        - tt
        - tw
        - ty
        - ug
        - uk
        - ur
        - uz
        - ve
        - vi
        - vo
        - wa
        - wo
        - xh
        - yi
        - yo
        - za
        - zh
        - zu
    Permission:
      title: Permission
      type: object
      description: A permission in the system.
      x-examples:
        example:
          id: 9bsv0s46s6s002p9ltq0
          kind: "*"
          created_at: "2023-01-01T00:00:00Z"
          updated_at: null
      properties:
        id:
          type: string
          description: Unique identifier of the user.
          example: 9bsv0s46s6s002p9ltq0
        kind:
          $ref: "#/components/schemas/PermissionKind"
        subject:
          type: string
          example: 9bsv0s46s6s002p9ltq0
        target:
          type: string
          example: 9bsv0s46s6s002p9ltq0
        created_at:
          type: string
          format: date-time
          description: Date when the user was created.
        updated_at:
          type: string
          format: date-time
          description: Date when the user was updated.
          nullable: true
      required:
        - id
        - kind
        - subject
        - target
        - created_at
        - updated_at
    PermissionKind:
      title: PermissionKind
      type: string
      description: Kind of a permission.
      enum:
        - "*"
        - create
        - write
        - read
        - delete
    Role:
      title: Role
      type: object
      description: A role in the system.
      x-examples:
        example:
          id: 9bsv0s46s6s002p9ltq0
          name: Collaborators
          description: Users who can collaborate on the project.
          members:
            - 9bsv0s46s6s002p9ltq0
          permissions:
            - 9bsv0s46s6s002p9ltq0
          created_at: "2023-01-01T00:00:00Z"
          updated_at: null
      properties:
        id:
          type: string
          description: Unique identifier of the role.
          example: 9bsv0s46s6s002p9ltq0
        name:
          type: string
          description: Name of the role.
          maxLength: 120
          example: Collaborators
          minLength: 3
        description:
          type: string
          description: Description of the role.
          maxLength: 500
          example: Users who can collaborate on the project.
          minLength: 5
          nullable: true
        members:
          type: array
          description: IDs of the users assigned to the role.
          uniqueItems: true
          items:
            type: string
            example: 9bsv0s46s6s002p9ltq0
        permissions:
          type: array
          description: IDs of the permissions assigned to the role.
          uniqueItems: true
          items:
            type: string
            example: 9bsv0s46s6s002p9ltq0
        created_at:
          type: string
          format: date-time
          description: Date when the organization was created.
        updated_at:
          type: string
          format: date-time
          description: Date when the organization was updated.
          nullable: true
      required:
        - id
        - name
        - members
        - permissions
        - created_at
        - updated_at
    ResourceType:
      title: ResourceType
      type: string
      enum:
        - Assignment
        - Attachment
        - Comment
        - Document
        - Issue
        - IssueRelation
        - Label
        - Namespace
        - Organization
        - Permission
        - Project
        - ResourceType
        - Role
        - Todo
        - User
  examples: {}
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        password:
          tokenUrl: /oauth/token
          scopes:
            organization: Read and write access to organizations.
            organization.read: Read access to organizations.
            user: Read and write access to users.
            user.read: Read access to users.
            todo: Read and write access to todo items.
            todo.read: Read access to todo items.
          refreshUrl: /oauth/authorize
        clientCredentials:
          tokenUrl: /oauth/token
          refreshUrl: /oauth/authorize
          scopes:
            organization: Read and write access to organizations.
            organization.read: Read access to organizations.
            user: Read and write access to users.
            user.read: Read access to users.
            todo: Read and write access to todo items.
            todo.read: Read access to todo items.
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            organization: Read and write access to organizations.
            organization.read: Read access to organizations.
            user: Read and write access to users.
            user.read: Read access to users.
            todo: Read and write access to todo items.
            todo.read: Read access to todo items.
            role: Read and write access to roles.
            role.read: Read access to roles.
  responses:
    "201":
      description: Example response
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            properties:
              id:
                type: string
                description: ID of the newly created resource.
            required:
              - id
    "400":
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HTTPError"
          examples:
            example:
              value:
                message: Invalid input given
    "401":
      description: Unauthorized request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HTTPError"
          examples:
            example:
              value:
                message: Unauthorized request
    "403":
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HTTPError"
          examples:
            example:
              value:
                message: The requested operation is forbidden
    "404":
      description: The requested resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HTTPError"
          examples:
            example:
              value:
                message: The requested resource not found
    "500":
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HTTPError"
          examples:
            example:
              value:
                message: Internal Server Error
  parameters:
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Number of resources to skip.
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
      description: Number of resources to return.
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
        example: 9bsv0s46s6s002p9ltq0
      description: ID of the resource.
    resourceId:
      name: resourceId
      in: path
      required: true
      schema:
        type: string
        example: Todo:9bsv0s46s6s002p9ltq0
      description: ID of the resource combined with its resource type.
    force:
      name: force
      in: query
      required: false
      schema:
        type: boolean
      description: Irreversibly delete the user.
    roles:
      name: roles
      in: query
      required: true
      schema:
        type: array
        items:
          type: string
          enum:
            - Owner
            - Admin
            - Support
      description: ID of a role.
  requestBodies:
    UserPatch:
      content:
        application/json:
          schema:
            type: object
            properties:
              username:
                type: string
                description: The unique username of the user.
                pattern: "^[a-z0-9-_]{3,50}$"
                minLength: 3
                maxLength: 50
                example: test-user
              first_name:
                type: string
                description: First name of the user.
                minLength: 1
                maxLength: 50
                example: Test
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              last_name:
                type: string
                description: Last name of the user.
                example: User
                minLength: 1
                maxLength: 50
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              email:
                type: string
                format: email
                example: user@example.com
                minLength: 6
                maxLength: 254
                description: Email address of the user.
              password:
                type: string
                format: password
                maxLength: 64
                minLength: 8
                example: super-secret
                description: Password of the user. Required together with the new_password field.
              new_password:
                type: string
                format: password
                maxLength: 64
                minLength: 8
                example: super-secret
                description: New password of the user.
              picture:
                type: string
                description: Profile picture of the user.
                format: uri
                example: "https://example.com/users/my-user.png"
                maxLength: 2000
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              title:
                type: string
                description: Work title of the user.
                example: Senior Software Engineer
                minLength: 3
                maxLength: 50
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              bio:
                type: string
                description: Self description of the user.
                maxLength: 500
                example: I'm working smart on software.
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              address:
                type: string
                minLength: 3
                maxLength: 500
                example: Remote
                description: Working address of the user.
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              phone:
                type: string
                example: "+15555551234"
                minLength: 7
                maxLength: 16
                description: Phone number of the user.
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              links:
                type: array
                description: Links to show on profile page.
                uniqueItems: true
                items:
                  type: string
                  format: uri
                  example: "https://example.com/my-user"
                  maxLength: 2000
              languages:
                type: array
                description: Languages of the user.
                uniqueItems: true
                items:
                  $ref: "#/components/schemas/Language"
              status:
                $ref: "#/components/schemas/UserStatus"
          examples:
            example:
              value:
                username: test-user
                first_name: Test
                last_name: User
                email: user@example.com
                picture: "https://example.com/users/my-user.png"
                title: Senior Software Engineer
                bio: I'm working smart on software.
                address: Remote
                phone: "+15555551234"
                links:
                  - "https://example.com/my-user"
                languages:
                  - aa
                status: active
      description: ""
    UserCreate:
      content:
        application/json:
          schema:
            type: object
            properties:
              username:
                type: string
                description: The unique username of the user.
                pattern: "^[a-z0-9-_]{3,50}$"
                minLength: 3
                maxLength: 50
                example: test-user
              first_name:
                type: string
                description: First name of the user.
                minLength: 1
                maxLength: 50
                example: Test
                nullable: true
              last_name:
                type: string
                description: Last name of the user.
                example: User
                minLength: 1
                maxLength: 50
                nullable: true
              email:
                type: string
                format: email
                example: user@example.com
                minLength: 6
                maxLength: 254
                description: Email address of the user.
              password:
                type: string
                minLength: 8
                maxLength: 64
                example: super-secret
                format: password
                description: Password of the user.
              picture:
                type: string
                description: Profile picture of the user.
                format: uri
                example: "https://example.com/users/my-user.png"
                maxLength: 2000
                nullable: true
              title:
                type: string
                description: Work title of the user.
                example: Senior Software Engineer
                minLength: 3
                maxLength: 50
                nullable: true
              bio:
                type: string
                description: Self description of the user.
                maxLength: 500
                example: I'm working smart on software.
                nullable: true
              address:
                type: string
                minLength: 3
                maxLength: 500
                example: Remote
                description: Working address of the user.
                nullable: true
              phone:
                type: string
                example: "+15555551234"
                minLength: 7
                maxLength: 16
                description: Phone number of the user.
                nullable: true
              links:
                type: array
                description: Links to show on profile page.
                uniqueItems: true
                nullable: true
                items:
                  type: string
                  format: uri
                  example: "https://example.com/my-user"
                  maxLength: 2000
              languages:
                type: array
                description: Languages of the user.
                uniqueItems: true
                nullable: true
                items:
                  $ref: "#/components/schemas/Language"
            required:
              - username
              - email
              - password
    TodoCreate:
      content:
        application/json:
          schema:
            type: object
            properties:
              title:
                type: string
                minLength: 3
                maxLength: 250
                example: Do something great
                description: Title of the todo item.
              description:
                type: string
                minLength: 10
                maxLength: 500
                example: I'll make the world a better place today.
                description: Description of the todo item.
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              priority:
                $ref: "#/components/schemas/TodoPriority"
              owned_by:
                type: string
                description: ID of the user who owns the todo item.
              due_date:
                type: string
                format: date-time
                description: Completion due date of the todo item.
                nullable: true
                x-go-type: "Optional[*time.Time]"
                x-go-type-skip-optional-pointer: true
            required:
              - title
              - priority
              - owned_by
    TodoPatch:
      content:
        application/json:
          schema:
            type: object
            properties:
              title:
                type: string
                minLength: 3
                maxLength: 250
                example: Do something great
                description: Title of the todo item.
              description:
                type: string
                minLength: 10
                maxLength: 500
                example: I'll make the world a better place today.
                description: Description of the todo item.
                nullable: true
                x-go-type: "Optional[string]"
                x-go-type-skip-optional-pointer: true
              priority:
                $ref: "#/components/schemas/TodoPriority"
              completed:
                type: boolean
                description: Completion status of the todo item.
              owned_by:
                type: string
                description: ID of the user who owns the todo item.
              due_date:
                type: string
                format: date-time
                description: Completion due date of the todo item.
                nullable: true
                x-go-type: "Optional[*time.Time]"
                x-go-type-skip-optional-pointer: true
    OrganizationCreate:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                description: Name of the organization.
                maxLength: 120
                example: ACME Inc.
                minLength: 1
              email:
                type: string
                format: email
                example: info@example.com
                minLength: 6
                maxLength: 254
                description: Email address of the organization.
              logo:
                type: string
                description: Logo of the organization.
                format: uri
                example: "https://example.com/static/logo.png"
                maxLength: 2000
              website:
                type: string
                description: Work title of the user.
                format: uri
                example: "https://example.com"
                maxLength: 2000
            required:
              - name
              - email
    OrganizationPatch:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                description: Name of the organization.
                maxLength: 120
                example: ACME Inc.
                minLength: 1
              email:
                type: string
                format: email
                example: info@example.com
                minLength: 6
                maxLength: 254
                description: Email address of the organization.
              logo:
                type: string
                description: Logo of the organization.
                format: uri
                example: "https://example.com/static/logo.png"
                maxLength: 2000
              website:
                type: string
                description: Work title of the user.
                format: uri
                example: "https://example.com"
                maxLength: 2000
              status:
                $ref: "#/components/schemas/OrganizationStatus"
    PermissionCreate:
      content:
        application/json:
          schema:
            type: object
            properties:
              kind:
                $ref: "#/components/schemas/PermissionKind"
              subject:
                type: object
                example: "user:9bsv0s46s6s002p9ltq0"
                required:
                  - resourceType
                  - id
                properties:
                  resourceType:
                    $ref: "#/components/schemas/ResourceType"
                  id:
                    type: string
                    example: 9bsv0s46s6s002p9ltq0
              target:
                type: object
                example: "user:9bsv0s46s6s002p9ltq0"
                required:
                  - resourceType
                  - id
                properties:
                  resourceType:
                    $ref: "#/components/schemas/ResourceType"
                  id:
                    type: string
                    example: 9bsv0s46s6s002p9ltq0
            required:
              - kind
              - subject
              - target
    PermissionPatch:
      content:
        application/json:
          schema:
            type: object
            properties:
              kind:
                $ref: "#/components/schemas/PermissionKind"
            required:
              - kind
    RoleCreate:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                description: Name of the role.
                maxLength: 120
                example: Contributors
                minLength: 3
              description:
                type: string
                example: Users who can collaborate on the project.
                minLength: 5
                maxLength: 500
                description: Description of the role.
            required:
              - name
    RolePatch:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                maxLength: 120
                minLength: 3
                description: Name of the role.
                example: Contributors
              description:
                type: string
                minLength: 5
                maxLength: 500
                description: Description of the role.
                example: Users who can collaborate on the project.
paths:
  /v1/users:
    get:
      summary: Get all users
      tags:
        - User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1UsersGet
      description: Returns the paginated list of users
      parameters:
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
      security:
        - oauth2:
            - user.read
    post:
      summary: Create new user
      tags:
        - User
      operationId: v1UsersCreate
      responses:
        "201":
          $ref: "#/components/responses/201"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "500":
          $ref: "#/components/responses/500"
      requestBody:
        $ref: "#/components/requestBodies/UserCreate"
      description: Create a new user.
      security:
        - oauth2:
            - user
  "/v1/users/{id}":
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      summary: Get user
      tags:
        - User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1UserGet
      description: Return the requested user by its ID.
      security:
        - oauth2:
            - user.read
    delete:
      summary: Delete the user with the given ID.
      tags:
        - User
      operationId: v1UserDelete
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Delete a user by its ID. The user is not deleted irreversibly until the "force" parameter is set to true.
      parameters:
        - $ref: "#/components/parameters/force"
      security:
        - oauth2:
            - user
    patch:
      summary: Update user
      tags:
        - User
      operationId: v1UserUpdate
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Update the given user.
      requestBody:
        $ref: "#/components/requestBodies/UserPatch"
      security:
        - oauth2:
            - user
  /v1/todos:
    get:
      summary: Get todo item
      tags:
        - Todo
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: "#/components/schemas/Todo"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      parameters:
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
        - schema:
            type: boolean
          in: query
          name: completed
          description: Completion status of the items.
      operationId: v1TodosGet
      description: Returns all todo items belonging to the current user.
      security:
        - oauth2:
            - todo.read
    post:
      summary: Create todo item
      operationId: v1TodosCreate
      responses:
        "201":
          $ref: "#/components/responses/201"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "500":
          $ref: "#/components/responses/500"
      description: Create a new todo item.
      security:
        - oauth2:
            - todo
      requestBody:
        $ref: "#/components/requestBodies/TodoCreate"
      tags:
        - Todo
  "/v1/todos/{id}":
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      summary: Get todo item
      tags:
        - Todo
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Todo"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1TodoGet
      description: Return a todo item based on the todo id belonging to the current user.
      security:
        - oauth2:
            - todo.read
    delete:
      summary: Delete todo item
      operationId: v1TodoDelete
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      tags:
        - Todo
      description: Delete todo by its ID.
      security:
        - oauth2:
            - todo
    patch:
      summary: Update todo
      operationId: v1TodoUpdate
      requestBody:
        $ref: "#/components/requestBodies/TodoPatch"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Todo"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Update the given todo
      tags:
        - Todo
      security:
        - oauth2:
            - todo
  /v1/organizations:
    get:
      summary: Get organizations
      tags:
        - Organization
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: "#/components/schemas/Organization"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1OrganizationsGet
      description: Returns the list of organizations in the system.
      security:
        - oauth2:
            - organization.read
      parameters:
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
    post:
      summary: Create organization
      operationId: v1OrganizationsCreate
      responses:
        "201":
          $ref: "#/components/responses/201"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "500":
          $ref: "#/components/responses/500"
      description: Create a new organization.
      security:
        - oauth2:
            - organization
      tags:
        - Organization
      requestBody:
        $ref: "#/components/requestBodies/OrganizationCreate"
  "/v1/organizations/{id}":
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      summary: Get organization
      tags:
        - Organization
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1OrganizationGet
      security:
        - oauth2:
            - organization.read
      description: Returns the given organization by its ID.
    delete:
      summary: Delete organization
      operationId: v1OrganizationDelete
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Delete the organization by its ID.
      security:
        - oauth2:
            - organization
      tags:
        - Organization
      parameters:
        - $ref: "#/components/parameters/force"
    patch:
      summary: Update organization
      operationId: v1OrganizationUpdate
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Update the organization by its ID.
      security:
        - oauth2:
            - organization
      tags:
        - Organization
      requestBody:
        $ref: "#/components/requestBodies/OrganizationPatch"
  "/v1/organizations/{id}/members":
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      summary: Get organization members
      tags:
        - Organization
        - User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1OrganizationMembersGet
      security:
        - oauth2:
            - organization.read
            - user.read
      description: Return the users that are members of the organization.
    post:
      summary: Add organization member
      operationId: v1OrganizationMembersAdd
      responses:
        "201":
          $ref: "#/components/responses/201"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Add an existing user to an organization.
      security:
        - oauth2:
            - organization
      tags:
        - Organization
        - User
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: ID of the user to add.
                  example: 9bsv0s46s6s002p9ltq0
              required:
                - user_id
  "/v1/organizations/{id}/members/{user_id}":
    parameters:
      - $ref: "#/components/parameters/id"
      - schema:
          type: string
          example: 9bsv0s46s6s002p9ltq0
        name: user_id
        in: path
        required: true
        description: ID of the user.
    delete:
      summary: Remove organization member
      operationId: v1OrganizationMemberRemove
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Removes a member from the organization
      security:
        - oauth2:
            - organization
      tags:
        - Organization
        - User
  "/v1/organizations/${id}/roles":
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      summary: Get organization roles
      description: Return the roles that are assigned to the organization.
      operationId: v1OrganizationRolesGet
      tags:
        - Organization
        - Role
      security:
        - oauth2:
            - organization.read
            - role.read
      parameters:
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: "#/components/schemas/Role"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    post:
      summary: Create a new role in the organization
      operationId: v1OrganizationRolesCreate
      responses:
        "201":
          $ref: "#/components/responses/201"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Create a new role and assign it to the organization.
      security:
        - oauth2:
            - organization
            - role
      tags:
        - Organization
        - Role
      requestBody:
        $ref: "#/components/requestBodies/RoleCreate"
  "/v1/organizations/${id}/roles/{role_id}":
    parameters:
      - $ref: "#/components/parameters/id"
      - schema:
          type: string
          example: 9bsv0s46s6s002p9ltq0
        name: role_id
        in: path
        required: true
        description: ID of the role.
    get:
      summary: Get organization role
      operationId: v1OrganizationRoleGet
      tags:
        - Organization
        - Role
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      security:
        - oauth2:
            - organization.read
            - role.read
      description: Returns the given organization by its ID.
    patch:
      summary: Update organization role
      operationId: v1OrganizationRoleUpdate
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Update the organization role by its ID.
      security:
        - oauth2:
            - organization
            - role
      tags:
        - Organization
        - Role
      requestBody:
        $ref: "#/components/requestBodies/RolePatch"
    delete:
      summary: Delete organization role
      operationId: v1OrganizationRoleDelete
      tags:
        - Organization
        - Role
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Deletes a role that is assigned to the organization.
      security:
        - oauth2:
            - organization
            - role
  "/v1/organizations/{id}/roles/{role_id}/members":
    parameters:
      - $ref: "#/components/parameters/id"
      - schema:
          type: string
          example: 9bsv0s46s6s002p9ltq0
        name: role_id
        in: path
        required: true
        description: ID of the role.
    get:
      summary: Get organization role members
      tags:
        - Organization
        - Role
        - User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1OrganizationRoleMembersGet
      security:
        - oauth2:
            - organization.read
            - role.read
            - user.read
      description: Return the users that are members of the organization's role.
    post:
      summary: Add organization role member
      operationId: v1OrganizationRoleMembersAdd
      responses:
        "201":
          $ref: "#/components/responses/201"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Add an existing user to an organization's role.
      security:
        - oauth2:
            - organization
            - role
      tags:
        - Organization
        - Role
        - User
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: ID of the user to add.
                  example: 9bsv0s46s6s002p9ltq0
              required:
                - user_id
  "/v1/organizations/{id}/roles/{role_id}/members/{user_id}":
    parameters:
      - $ref: "#/components/parameters/id"
      - schema:
          type: string
          example: 9bsv0s46s6s002p9ltq0
        name: role_id
        in: path
        required: true
        description: ID of the role.
      - schema:
          type: string
          example: 9bsv0s46s6s002p9ltq0
        name: user_id
        in: path
        required: true
        description: ID of the user.
    delete:
      summary: Remove organization role member
      operationId: v1OrganizationRoleMemberRemove
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Removes a member from the organization's role
      security:
        - oauth2:
            - organization
            - role
      tags:
        - Organization
        - Role
        - User
  /v1/permissions:
    post:
      summary: Create permission
      operationId: v1PermissionsCreate
      responses:
        "201":
          $ref: "#/components/responses/201"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "500":
          $ref: "#/components/responses/500"
      description: Create a new permission for a subject to the given target.
      security:
        - oauth2: []
      tags:
        - Permission
      requestBody:
        $ref: "#/components/requestBodies/PermissionCreate"
  "/v1/permissions/{id}":
    parameters:
      - $ref: "#/components/parameters/id"
    patch:
      summary: Update permission
      operationId: v1PermissionUpdate
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Update a permission.
      security:
        - oauth2: []
      tags:
        - Permission
      requestBody:
        $ref: "#/components/requestBodies/PermissionPatch"
    delete:
      summary: Delete permission
      operationId: v1PermissionDelete
      responses:
        "204":
          description: No Content
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Delete a permission by its ID.
      security:
        - oauth2: []
      tags:
        - Permission
    get:
      summary: Get permission
      operationId: v1PermissionGet
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Permission"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Get a permission by its ID.
      security:
        - oauth2: []
      tags:
        - Permission
  "/v1/permissions/resources/{resourceId}":
    parameters:
      - $ref: "#/components/parameters/resourceId"
    get:
      summary: Get permissions for a resource
      operationId: v1PermissionResourceGet
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Permission"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Get all permissions the caller have for a given resource.
      security:
        - oauth2: []
      tags:
        - Permission
  "/v1/permissions/has-relations/{resourceId}":
    parameters:
      - $ref: "#/components/parameters/resourceId"
    get:
      summary: Check relations to resource
      operationId: v1PermissionHasRelations
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: boolean
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
      description: Check if the caller has any relations to a given resource.
      security:
        - oauth2: []
      tags:
        - Permission
  /v1/permissions/has-system-role:
    parameters: []
    get:
      summary: Check system role assignment
      operationId: v1PermissionHasSystemRole
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: boolean
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"
      description: "Check if the user is member of one or more system roles."
      security:
        - oauth2: []
      tags:
        - Permission
      parameters:
        - $ref: "#/components/parameters/roles"
  /v1/system/health:
    get:
      summary: Get system health
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemHealth"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1SystemHealth
      description: Returns the health of registered components.
      security: []
      tags:
        - System
  /v1/system/heartbeat:
    get:
      summary: Get heartbeat
      tags:
        - System
      responses:
        "200":
          description: OK
          content:
            text/plain:
              schema:
                type: string
                enum:
                  - OK
        "500":
          $ref: "#/components/responses/500"
      operationId: v1SystemHeartbeat
      description: Returns 200 OK if the service is reachable.
      security: []
  /v1/system/license:
    get:
      summary: Get license info
      tags:
        - System
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemLicense"
        "403":
          $ref: "#/components/responses/403"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1SystemLicense
      description: Return the license information. The license information is only available to entitled users.
      security:
        - oauth2: []
  /v1/system/version:
    get:
      summary: Get system version
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemVersion"
        "500":
          $ref: "#/components/responses/500"
      operationId: v1SystemVersion
      description: Returns the version information of the system.
      security: []
      tags:
        - System