Humanitec API — ArtefactVersion

naftiko: 1.0.0-alpha2
info:
  label: Humanitec API — ArtefactVersion
  description: 'Humanitec API — ArtefactVersion. 6 operations. Lead operation: List all Artefacts Versions in the org.. Self-contained
    Naftiko capability covering one Humanitec business surface.'
  tags:
  - Humanitec
  - ArtefactVersion
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    HUMANITEC_API_KEY: HUMANITEC_API_KEY
capability:
  consumes:
  - type: http
    namespace: humanitec-artefactversion
    baseUri: https://api.humanitec.io
    description: Humanitec API — ArtefactVersion business capability. Self-contained, no shared references.
    resources:
    - name: orgs-orgId-artefact-versions
      path: /orgs/{orgId}/artefact-versions
      operations:
      - name: listartefactversionsinorg
        method: GET
        description: List all Artefacts Versions in the org.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: The organization ID.
          required: true
        - name: name
          in: query
          type: string
          description: (Optional) Filter Artefact Versions by name.
        - name: reference
          in: query
          type: string
          description: (Optional) Filter Artefact Versions by the reference to a Version of the same Artefact. This cannot
            be used together with `name`.
        - name: archived
          in: query
          type: boolean
          description: (Optional) Filter for non-archived Artefact Versions. If no filter is defined only non-archived Artefact
            Versions are returned, if the filter is true both archi
        - name: type
          in: query
          type: string
          description: (Optional) Filter by artefact type.
      - name: createartefactversion
        method: POST
        description: Register a new Artefact Version with your organization.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: The organization ID.
          required: true
        - name: vcs
          in: query
          type: string
          description: (Optional) Which version control system the version comes from. Default value is "git". If this parameter
            is not supplied or its value is "git", the provided re
        - name: dry_run
          in: query
          type: boolean
          description: Optionally validate the request but do not persist the actual artefact. If the Accept type is set to
            "application/x.workload-deployment-set+json" or "applicatio
        - name: Accept
          in: header
          type: string
          description: Indicates which content types the client is able to understand.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-artefact-versions-convert-score
      path: /orgs/{orgId}/artefact-versions/convert-score
      operations:
      - name: convertscoretoset
        method: POST
        description: Convert a Score specification, optional overrides, and extensions into the contents for a deployment
          set.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: The organization ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-artefact-versions-artefactVersionId
      path: /orgs/{orgId}/artefact-versions/{artefactVersionId}
      operations:
      - name: getartefactversion
        method: GET
        description: Get an Artefacts Versions.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: The organization ID.
          required: true
        - name: artefactVersionId
          in: path
          type: string
          description: The Artefact Version ID.
          required: true
    - name: orgs-orgId-artefacts-artefactId-versions
      path: /orgs/{orgId}/artefacts/{artefactId}/versions
      operations:
      - name: listartefactversions
        method: GET
        description: List all Artefact Versions of an Artefact.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: The organization ID.
          required: true
        - name: artefactId
          in: path
          type: string
          description: The Artefact ID.
          required: true
        - name: archived
          in: query
          type: boolean
          description: (Optional) Filter for non-archived Artefact Versions. If no filter is defined only non-archived Artefact
            Versions are returned, if the filter is true both archi
        - name: reference
          in: query
          type: string
          description: (Optional) Filter Artefact Versions by by name including a version or digest.
        - name: limit
          in: query
          type: integer
          description: (Optional) Limit the number of versions returned by the endpoint.
    - name: orgs-orgId-artefacts-artefactId-versions-versionId
      path: /orgs/{orgId}/artefacts/{artefactId}/versions/{versionId}
      operations:
      - name: patchartefactversion
        method: PATCH
        description: Update Version of an Artefact.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: path
          type: string
          description: The organization ID.
          required: true
        - name: artefactId
          in: path
          type: string
          description: The Artefact ID.
          required: true
        - name: versionId
          in: path
          type: string
          description: The Version ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
  exposes:
  - type: rest
    namespace: humanitec-artefactversion-rest
    port: 8080
    description: REST adapter for Humanitec API — ArtefactVersion. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/orgs/{orgid}/artefact-versions
      name: orgs-orgid-artefact-versions
      description: REST surface for orgs-orgId-artefact-versions.
      operations:
      - method: GET
        name: listartefactversionsinorg
        description: List all Artefacts Versions in the org.
        call: humanitec-artefactversion.listartefactversionsinorg
        with:
          orgId: rest.orgId
          name: rest.name
          reference: rest.reference
          archived: rest.archived
          type: rest.type
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createartefactversion
        description: Register a new Artefact Version with your organization.
        call: humanitec-artefactversion.createartefactversion
        with:
          orgId: rest.orgId
          vcs: rest.vcs
          dry_run: rest.dry_run
          Accept: rest.Accept
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/artefact-versions/convert-score
      name: orgs-orgid-artefact-versions-convert-score
      description: REST surface for orgs-orgId-artefact-versions-convert-score.
      operations:
      - method: POST
        name: convertscoretoset
        description: Convert a Score specification, optional overrides, and extensions into the contents for a deployment
          set.
        call: humanitec-artefactversion.convertscoretoset
        with:
          orgId: rest.orgId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/artefact-versions/{artefactversionid}
      name: orgs-orgid-artefact-versions-artefactversionid
      description: REST surface for orgs-orgId-artefact-versions-artefactVersionId.
      operations:
      - method: GET
        name: getartefactversion
        description: Get an Artefacts Versions.
        call: humanitec-artefactversion.getartefactversion
        with:
          orgId: rest.orgId
          artefactVersionId: rest.artefactVersionId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/artefacts/{artefactid}/versions
      name: orgs-orgid-artefacts-artefactid-versions
      description: REST surface for orgs-orgId-artefacts-artefactId-versions.
      operations:
      - method: GET
        name: listartefactversions
        description: List all Artefact Versions of an Artefact.
        call: humanitec-artefactversion.listartefactversions
        with:
          orgId: rest.orgId
          artefactId: rest.artefactId
          archived: rest.archived
          reference: rest.reference
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/artefacts/{artefactid}/versions/{versionid}
      name: orgs-orgid-artefacts-artefactid-versions-versionid
      description: REST surface for orgs-orgId-artefacts-artefactId-versions-versionId.
      operations:
      - method: PATCH
        name: patchartefactversion
        description: Update Version of an Artefact.
        call: humanitec-artefactversion.patchartefactversion
        with:
          orgId: rest.orgId
          artefactId: rest.artefactId
          versionId: rest.versionId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: humanitec-artefactversion-mcp
    port: 9090
    transport: http
    description: MCP adapter for Humanitec API — ArtefactVersion. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: list-all-artefacts-versions-org
      description: List all Artefacts Versions in the org.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-artefactversion.listartefactversionsinorg
      with:
        orgId: tools.orgId
        name: tools.name
        reference: tools.reference
        archived: tools.archived
        type: tools.type
      outputParameters:
      - type: object
        mapping: $.
    - name: register-new-artefact-version-your
      description: Register a new Artefact Version with your organization.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-artefactversion.createartefactversion
      with:
        orgId: tools.orgId
        vcs: tools.vcs
        dry_run: tools.dry_run
        Accept: tools.Accept
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: convert-score-specification-optional-overrides
      description: Convert a Score specification, optional overrides, and extensions into the contents for a deployment set.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-artefactversion.convertscoretoset
      with:
        orgId: tools.orgId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-artefacts-versions
      description: Get an Artefacts Versions.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-artefactversion.getartefactversion
      with:
        orgId: tools.orgId
        artefactVersionId: tools.artefactVersionId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-all-artefact-versions-artefact
      description: List all Artefact Versions of an Artefact.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-artefactversion.listartefactversions
      with:
        orgId: tools.orgId
        artefactId: tools.artefactId
        archived: tools.archived
        reference: tools.reference
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: update-version-artefact
      description: Update Version of an Artefact.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: humanitec-artefactversion.patchartefactversion
      with:
        orgId: tools.orgId
        artefactId: tools.artefactId
        versionId: tools.versionId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.