openapi: 3.0.1
info:
  title: Scopes API
  description: Provides access to the scopes in Hyperproof.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/scopes
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/scopes
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/scopes
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get Scopes
      description: >
        `GET /`


        #### Description


        Retrieves details of all scopes within an organization, including their
        permissions, boundaries, and associated metadata.
      operationId: get-scopes
      responses:
        '200':
          description: The list of scopes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeCollection'
              example:
                - id: cb1a06f4-8ed9-4614-a17b-f8671194687e
                  name: Acme
                  owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                  description: The Acme Corp scope
                  parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
                  pathIds:
                    - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
                    - cb1a06f4-8ed9-4614-a17b-f8671194687e
                  pathNames:
                    - Acme-Parent
                    - Acme
    patch:
      summary: Bulk Update Scopes
      description: >
        `PATCH /`


        #### Description


        Updates one or more scopes within an organization, modifying their
        definitions, permissions, or associated metadata.
      operationId: patch-scopes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkScopePatch'
            example:
              scopeIds:
                - cb1a06f4-8ed9-4614-a17b-f8671194687e
              patch:
                name: Acme
                owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                description: The Acme Corp scope
      responses:
        '200':
          description: The list of updated scopes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeCollection'
              example:
                - id: cb1a06f4-8ed9-4614-a17b-f8671194687e
                  name: Acme
                  owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                  description: The Acme Corp scope
                  parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
                  pathIds:
                    - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
                    - cb1a06f4-8ed9-4614-a17b-f8671194687e
                  pathNames:
                    - Acme-Parent
                    - Acme
    post:
      summary: Create Scope
      description: >
        `POST /`


        #### Description


        Creates a new scope within an organization, defining its permissions,
        boundaries, and associated metadata.
      operationId: add-scope
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopePost'
            example:
              name: New Scope
              owner: 23b806db-bad2-4f7a-b8d1-ac117790999b
              parentId: b7c74ee5-7c13-41a3-9395-d789a13cb249
              description: A newly created scope
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  textValue: Antonio Moreno
      responses:
        '200':
          description: The newly created scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scope'
              example:
                id: cb1a06f4-8ed9-4614-a17b-f8671194687e
                name: Acme
                owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                description: The Acme Corp scope
                parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
                pathIds:
                  - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
                  - cb1a06f4-8ed9-4614-a17b-f8671194687e
                pathNames:
                  - Acme-Parent
                  - Acme
  /filter:
    post:
      summary: Filter Scopes
      description: >
        `POST /filter`


        #### Description


        Retrieves a set of scopes that match the specified filter criteria,
        returning their definitions, permissions, and related metadata.
      operationId: get-scopes-filtered
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopeFilter'
            example:
              programIds:
                - e8e2a5b6-767d-4345-86b9-a9d12a5836ee
      responses:
        '200':
          description: The list of scopes matching the filter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeCollection'
              example:
                - id: cb1a06f4-8ed9-4614-a17b-f8671194687e
                  name: Acme
                  owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                  description: The Acme Corp scope
                  parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
                  pathIds:
                    - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
                    - cb1a06f4-8ed9-4614-a17b-f8671194687e
                  pathNames:
                    - Acme-Parent
                    - Acme
  /{scopeId}:
    get:
      summary: Get Scope
      description: >
        `GET /{scopeId}`


        #### Description


        Retrieves details of a specific scope by its unique ID, including its
        permissions, boundaries, and associated metadata.
      operationId: get-scope
      parameters:
        - name: scopeId
          in: path
          description: Unique identifier of the scope.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The scope with the specified identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scope'
              example:
                id: cb1a06f4-8ed9-4614-a17b-f8671194687e
                name: Acme
                owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                description: The Acme Corp scope
                parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
                pathIds:
                  - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
                  - cb1a06f4-8ed9-4614-a17b-f8671194687e
                pathNames:
                  - Acme-Parent
                  - Acme
    patch:
      summary: Update Scope
      description: >
        `PATCH /{scopeId}`


        #### Description


        Updates an existing scope with new values, modifying its permissions,
        boundaries, or other defined attributes.
      operationId: patch-scope
      parameters:
        - name: scopeId
          in: path
          description: Unique identifier of the scope to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopePatch'
            example:
              id: f7cc82f5-cd53-43b7-986a-3de2fa327965
              name: Updated Scope
              owner: 23b806db-bad2-4f7a-b8d1-ac117790999b
              description: Scope description
              status: archived
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  textValue: Antonio Moreno
      responses:
        '200':
          description: The updated scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scope'
              example:
                id: cb1a06f4-8ed9-4614-a17b-f8671194687e
                name: Acme
                owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                description: The Acme Corp scope
                parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
                pathIds:
                  - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
                  - cb1a06f4-8ed9-4614-a17b-f8671194687e
                pathNames:
                  - Acme-Parent
                  - Acme
  /tree:
    post:
      summary: Get Scope Tree
      description: >
        `GET /tree`


        #### Description


        Retrieves the full scope tree, returning the hierarchical structure of
        scopes and their relationships within the organization.
      operationId: get-scope-tree
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopeTreeFilter'
            example:
              onlyActive: true
      responses:
        '200':
          description: The newly created scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeNode'
              example:
                scope:
                  id: cb1a06f4-8ed9-4614-a17b-f8671194687e
                  name: Acme
                  owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                  description: The Acme Corp scope
                  parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
                  pathIds:
                    - cb1a06f4-8ed9-4614-a17b-f8671194687e
                  pathNames:
                    - Acme
                children:
                  - id: 71f5fba2-bd08-4e7e-9e6c-05209956f22d
                    name: Acme-Child
                    owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
                    description: A child scope of Acme
                    parentId: cb1a06f4-8ed9-4614-a17b-f8671194687e
                    pathIds:
                      - cb1a06f4-8ed9-4614-a17b-f8671194687e
                      - 71f5fba2-bd08-4e7e-9e6c-05209956f22d
                    pathNames:
                      - Acme
                      - Acme-Child
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            scope.read: Grants read access to scopes
            scope.update: Grants update access to scopes
  schemas:
    BulkScopePatch:
      type: object
      properties:
        scopeIds:
          type: array
          description: The unique identifiers of the scopes to patch
          items:
            type: string
        patch:
          $ref: '#/components/schemas/ScopePatch'
      required:
        - scopeIds
        - patch
      example:
        scopeIds:
          - cb1a06f4-8ed9-4614-a17b-f8671194687e
        patch:
          name: Acme
          owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
          description: The Acme Corp scope
    Scope:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the scope within the organization
          example: string
        name:
          type: string
          description: Name of the scope
          example: string
        owner:
          type: string
          description: The unique identifier of the user who owns the scope
          example: string
        description:
          type: string
          description: Description of the scope
          example: string
        parentId:
          type: string
          description: >-
            The unique identifier for the scope's parent, or null for a
            top-level scope
          example: string
        pathIds:
          type: array
          items:
            type: string
          description: >-
            The unique identifiers for the scope's parents, starting from the
            top-most scope
          readOnly: true
        pathNames:
          type: array
          items:
            type: string
          description: Names of the scope's parents, starting from the top-most scope
          readOnly: true
      example:
        id: cb1a06f4-8ed9-4614-a17b-f8671194687e
        name: Acme
        owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
        description: The Acme Corp scope
        parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
        pathIds:
          - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
          - cb1a06f4-8ed9-4614-a17b-f8671194687e
        pathNames:
          - Acme-Parent
          - Acme
    ScopeCollection:
      type: array
      items:
        $ref: '#/components/schemas/Scope'
      example:
        - id: cb1a06f4-8ed9-4614-a17b-f8671194687e
          name: Acme
          owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
          description: The Acme Corp scope
          parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
          pathIds:
            - 6ff2fae7-02a8-4862-bf0c-61dbc0c33c23
            - cb1a06f4-8ed9-4614-a17b-f8671194687e
          pathNames:
            - Acme-Parent
            - Acme
    ScopeFilter:
      type: object
      properties:
        programIds:
          type: array
          items:
            type: string
      required:
        - programIds
      example:
        programIds:
          - e8e2a5b6-767d-4345-86b9-a9d12a5836ee
    ScopeNode:
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/Scope'
        children:
          type: array
          items:
            $ref: '#/components/schemas/Scope'
      example:
        scope:
          id: cb1a06f4-8ed9-4614-a17b-f8671194687e
          name: Acme
          owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
          description: The Acme Corp scope
          parentId: b38f3039-eaa6-4d2a-948d-821a01c79185
          pathIds:
            - cb1a06f4-8ed9-4614-a17b-f8671194687e
          pathNames:
            - Acme
        children:
          - id: 71f5fba2-bd08-4e7e-9e6c-05209956f22d
            name: Acme-Child
            owner: 402f37f8-6054-4138-be1f-9b22ec08a86b
            description: A child scope of Acme
            parentId: cb1a06f4-8ed9-4614-a17b-f8671194687e
            pathIds:
              - cb1a06f4-8ed9-4614-a17b-f8671194687e
              - 71f5fba2-bd08-4e7e-9e6c-05209956f22d
            pathNames:
              - Acme
              - Acme-Child
    ScopePatch:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the scope within the organization
        name:
          type: string
          description: The name of the scope
        owner:
          type: string
          description: The unique identifier of the user who owns the scope
        description:
          type: string
          description: The description of the scope
        status:
          type: string
          description: The status of the scope within the organization
          enum:
            - active
            - archived
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
      required:
        - id
      example:
        id: f7cc82f5-cd53-43b7-986a-3de2fa327965
        name: Updated Scope
        owner: 23b806db-bad2-4f7a-b8d1-ac117790999b
        description: Scope description
        status: archived
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            textValue: Antonio Moreno
    CustomFieldObjectValuePatch:
      type: object
      properties:
        fieldId:
          type: string
          description: Unique identifier for the custom field
        textValue:
          type: string
          description: Value if the field type is `text`
        numberValue:
          type: number
          description: Value if the field type is `number`
        dateValue:
          type: string
          description: Value if the field type is `date`
        userValue:
          type: string
          description: Value if the field type is `user`
        selections:
          type: array
          description: List of values for `textMultiSelect`
          items:
            type: string
    ScopePost:
      type: object
      properties:
        name:
          type: string
          description: The name of the scope
        owner:
          type: string
          description: The unique identifier of the user who owns the scope
        parentId:
          type: string
          description: >-
            The optional unique identifier of the scope for this scope's parent
            in a hierarchy of scopes
        description:
          type: string
          description: The description of the scope
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
      required:
        - name
        - owner
      example:
        name: New Scope
        owner: 23b806db-bad2-4f7a-b8d1-ac117790999b
        parentId: b7c74ee5-7c13-41a3-9395-d789a13cb249
        description: A newly created scope
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            textValue: Antonio Moreno
    ScopeTreeFilter:
      type: object
      properties:
        onlyActive:
          type: boolean
          description: Whether or not to exclude archived scopes in the results
      example:
        onlyActive: true
