lakeFS API — experimental

naftiko: 1.0.0-alpha2
info:
  label: lakeFS API — experimental
  description: 'lakeFS API — experimental. 18 operations. Lead operation: perform a login using an external authenticator.
    Self-contained Naftiko capability covering one Lakefs business surface.'
  tags:
  - Lakefs
  - experimental
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    LAKEFS_API_KEY: LAKEFS_API_KEY
capability:
  consumes:
  - type: http
    namespace: lakefs-experimental
    baseUri: ''
    description: lakeFS API — experimental business capability. Self-contained, no shared references.
    resources:
    - name: auth-external-principal-login
      path: /auth/external/principal/login
      operations:
      - name: externalprincipallogin
        method: POST
        description: perform a login using an external authenticator
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: auth-external-principals
      path: /auth/external/principals
      operations:
      - name: getexternalprincipal
        method: GET
        description: describe external principal by id
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: auth-users-userId-external-principals
      path: /auth/users/{userId}/external/principals
      operations:
      - name: createuserexternalprincipal
        method: POST
        description: attach external principal to user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: deleteuserexternalprincipal
        method: DELETE
        description: delete external principal from user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: auth-users-userId-external-principals-ls
      path: /auth/users/{userId}/external/principals/ls
      operations:
      - name: listuserexternalprincipals
        method: GET
        description: list user external policies attached to a user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: repositories-repository-branches-branch-hard_reset
      path: /repositories/{repository}/branches/{branch}/hard_reset
      operations:
      - name: hardresetbranch
        method: PUT
        description: hard reset branch
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ref
          in: query
          type: string
          description: After reset, branch will point at this reference.
          required: true
        - name: force
          in: query
          type: boolean
    - name: repositories-repository-branches-branch-objects-stat-user_metadata
      path: /repositories/{repository}/branches/{branch}/objects/stat/user_metadata
      operations:
      - name: updateobjectusermetadata
        method: PUT
        description: rewrite (all) object metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: repositories-repository-branches-branch-staging-pmpu
      path: /repositories/{repository}/branches/{branch}/staging/pmpu
      operations:
      - name: createpresignmultipartupload
        method: POST
        description: Initiate a multipart upload
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: repositories-repository-branches-branch-staging-pmpu-uploadId
      path: /repositories/{repository}/branches/{branch}/staging/pmpu/{uploadId}
      operations:
      - name: completepresignmultipartupload
        method: PUT
        description: Complete a presign multipart upload request
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: abortpresignmultipartupload
        method: DELETE
        description: Abort a presign multipart upload
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: repositories-repository-branches-branch-staging-pmpu-uploadId-parts-partNumber
      path: /repositories/{repository}/branches/{branch}/staging/pmpu/{uploadId}/parts/{partNumber}
      operations:
      - name: uploadpart
        method: PUT
        description: Return a presigned URL to upload into a presigned multipart upload.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: repositories-repository-branches-branch-staging-pmpu-uploadId-parts-partNumber-c
      path: /repositories/{repository}/branches/{branch}/staging/pmpu/{uploadId}/parts/{partNumber}/copy
      operations:
      - name: uploadpartcopy
        method: PUT
        description: Upload a part by copying part of another object.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: repositories-repository-pulls
      path: /repositories/{repository}/pulls
      operations:
      - name: listpullrequests
        method: GET
        description: list pull requests
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: status
          in: query
          type: string
      - name: createpullrequest
        method: POST
        description: create pull request
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: repositories-repository-pulls-pull_request
      path: /repositories/{repository}/pulls/{pull_request}
      operations:
      - name: getpullrequest
        method: GET
        description: get pull request
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatepullrequest
        method: PATCH
        description: update pull request
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: repositories-repository-pulls-pull_request-merge
      path: /repositories/{repository}/pulls/{pull_request}/merge
      operations:
      - name: mergepullrequest
        method: PUT
        description: merge pull request
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sts-login
      path: /sts/login
      operations:
      - name: stslogin
        method: POST
        description: perform a login with STS
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: bearer
      token: '{{env.LAKEFS_API_KEY}}'
  exposes:
  - type: rest
    namespace: lakefs-experimental-rest
    port: 8080
    description: REST adapter for lakeFS API — experimental. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/auth/external/principal/login
      name: auth-external-principal-login
      description: REST surface for auth-external-principal-login.
      operations:
      - method: POST
        name: externalprincipallogin
        description: perform a login using an external authenticator
        call: lakefs-experimental.externalprincipallogin
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/auth/external/principals
      name: auth-external-principals
      description: REST surface for auth-external-principals.
      operations:
      - method: GET
        name: getexternalprincipal
        description: describe external principal by id
        call: lakefs-experimental.getexternalprincipal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/auth/users/{userid}/external/principals
      name: auth-users-userid-external-principals
      description: REST surface for auth-users-userId-external-principals.
      operations:
      - method: POST
        name: createuserexternalprincipal
        description: attach external principal to user
        call: lakefs-experimental.createuserexternalprincipal
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deleteuserexternalprincipal
        description: delete external principal from user
        call: lakefs-experimental.deleteuserexternalprincipal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/auth/users/{userid}/external/principals/ls
      name: auth-users-userid-external-principals-ls
      description: REST surface for auth-users-userId-external-principals-ls.
      operations:
      - method: GET
        name: listuserexternalprincipals
        description: list user external policies attached to a user
        call: lakefs-experimental.listuserexternalprincipals
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/branches/{branch}/hard-reset
      name: repositories-repository-branches-branch-hard-reset
      description: REST surface for repositories-repository-branches-branch-hard_reset.
      operations:
      - method: PUT
        name: hardresetbranch
        description: hard reset branch
        call: lakefs-experimental.hardresetbranch
        with:
          ref: rest.ref
          force: rest.force
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/branches/{branch}/objects/stat/user-metadata
      name: repositories-repository-branches-branch-objects-stat-user-metadata
      description: REST surface for repositories-repository-branches-branch-objects-stat-user_metadata.
      operations:
      - method: PUT
        name: updateobjectusermetadata
        description: rewrite (all) object metadata
        call: lakefs-experimental.updateobjectusermetadata
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/branches/{branch}/staging/pmpu
      name: repositories-repository-branches-branch-staging-pmpu
      description: REST surface for repositories-repository-branches-branch-staging-pmpu.
      operations:
      - method: POST
        name: createpresignmultipartupload
        description: Initiate a multipart upload
        call: lakefs-experimental.createpresignmultipartupload
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/branches/{branch}/staging/pmpu/{uploadid}
      name: repositories-repository-branches-branch-staging-pmpu-uploadid
      description: REST surface for repositories-repository-branches-branch-staging-pmpu-uploadId.
      operations:
      - method: PUT
        name: completepresignmultipartupload
        description: Complete a presign multipart upload request
        call: lakefs-experimental.completepresignmultipartupload
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: abortpresignmultipartupload
        description: Abort a presign multipart upload
        call: lakefs-experimental.abortpresignmultipartupload
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/branches/{branch}/staging/pmpu/{uploadid}/parts/{partnumber}
      name: repositories-repository-branches-branch-staging-pmpu-uploadid-parts-partnumber
      description: REST surface for repositories-repository-branches-branch-staging-pmpu-uploadId-parts-partNumber.
      operations:
      - method: PUT
        name: uploadpart
        description: Return a presigned URL to upload into a presigned multipart upload.
        call: lakefs-experimental.uploadpart
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/branches/{branch}/staging/pmpu/{uploadid}/parts/{partnumber}/copy
      name: repositories-repository-branches-branch-staging-pmpu-uploadid-parts-partnumber-c
      description: REST surface for repositories-repository-branches-branch-staging-pmpu-uploadId-parts-partNumber-c.
      operations:
      - method: PUT
        name: uploadpartcopy
        description: Upload a part by copying part of another object.
        call: lakefs-experimental.uploadpartcopy
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/pulls
      name: repositories-repository-pulls
      description: REST surface for repositories-repository-pulls.
      operations:
      - method: GET
        name: listpullrequests
        description: list pull requests
        call: lakefs-experimental.listpullrequests
        with:
          status: rest.status
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createpullrequest
        description: create pull request
        call: lakefs-experimental.createpullrequest
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/pulls/{pull-request}
      name: repositories-repository-pulls-pull-request
      description: REST surface for repositories-repository-pulls-pull_request.
      operations:
      - method: GET
        name: getpullrequest
        description: get pull request
        call: lakefs-experimental.getpullrequest
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updatepullrequest
        description: update pull request
        call: lakefs-experimental.updatepullrequest
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/repositories/{repository}/pulls/{pull-request}/merge
      name: repositories-repository-pulls-pull-request-merge
      description: REST surface for repositories-repository-pulls-pull_request-merge.
      operations:
      - method: PUT
        name: mergepullrequest
        description: merge pull request
        call: lakefs-experimental.mergepullrequest
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/sts/login
      name: sts-login
      description: REST surface for sts-login.
      operations:
      - method: POST
        name: stslogin
        description: perform a login with STS
        call: lakefs-experimental.stslogin
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: lakefs-experimental-mcp
    port: 9090
    transport: http
    description: MCP adapter for lakeFS API — experimental. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: perform-login-using-external-authenticator
      description: perform a login using an external authenticator
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lakefs-experimental.externalprincipallogin
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: describe-external-principal-id
      description: describe external principal by id
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: lakefs-experimental.getexternalprincipal
      outputParameters:
      - type: object
        mapping: $.
    - name: attach-external-principal-user
      description: attach external principal to user
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lakefs-experimental.createuserexternalprincipal
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-external-principal-user
      description: delete external principal from user
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: lakefs-experimental.deleteuserexternalprincipal
      outputParameters:
      - type: object
        mapping: $.
    - name: list-user-external-policies-attached
      description: list user external policies attached to a user
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: lakefs-experimental.listuserexternalprincipals
      outputParameters:
      - type: object
        mapping: $.
    - name: hard-reset-branch
      description: hard reset branch
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lakefs-experimental.hardresetbranch
      with:
        ref: tools.ref
        force: tools.force
      outputParameters:
      - type: object
        mapping: $.
    - name: rewrite-all-object-metadata
      description: rewrite (all) object metadata
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lakefs-experimental.updateobjectusermetadata
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: initiate-multipart-upload
      description: Initiate a multipart upload
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lakefs-experimental.createpresignmultipartupload
      outputParameters:
      - type: object
        mapping: $.
    - name: complete-presign-multipart-upload-request
      description: Complete a presign multipart upload request
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lakefs-experimental.completepresignmultipartupload
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: abort-presign-multipart-upload
      description: Abort a presign multipart upload
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: lakefs-experimental.abortpresignmultipartupload
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: return-presigned-url-upload-presigned
      description: Return a presigned URL to upload into a presigned multipart upload.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lakefs-experimental.uploadpart
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: upload-part-copying-part-another
      description: Upload a part by copying part of another object.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lakefs-experimental.uploadpartcopy
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-pull-requests
      description: list pull requests
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: lakefs-experimental.listpullrequests
      with:
        status: tools.status
      outputParameters:
      - type: object
        mapping: $.
    - name: create-pull-request
      description: create pull request
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lakefs-experimental.createpullrequest
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-pull-request
      description: get pull request
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: lakefs-experimental.getpullrequest
      outputParameters:
      - type: object
        mapping: $.
    - name: update-pull-request
      description: update pull request
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lakefs-experimental.updatepullrequest
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: merge-pull-request
      description: merge pull request
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: lakefs-experimental.mergepullrequest
      outputParameters:
      - type: object
        mapping: $.
    - name: perform-login-sts
      description: perform a login with STS
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: lakefs-experimental.stslogin
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.