Humanitec API — PipelineRuns

naftiko: 1.0.0-alpha2
info:
  label: Humanitec API — PipelineRuns
  description: 'Humanitec API — PipelineRuns. 11 operations. Lead operation: Create a Pipeline Run in the appropriate Pipeline
    based on the trigger and inputs.. Self-contained Naftiko capability covering one Humanitec business surface.'
  tags:
  - Humanitec
  - PipelineRuns
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    HUMANITEC_API_KEY: HUMANITEC_API_KEY
capability:
  consumes:
  - type: http
    namespace: humanitec-pipelineruns
    baseUri: https://api.humanitec.io
    description: Humanitec API — PipelineRuns business capability. Self-contained, no shared references.
    resources:
    - name: orgs-orgId-apps-appId-pipeline-runs
      path: /orgs/{orgId}/apps/{appId}/pipeline-runs
      operations:
      - name: createpipelinerunbytriggercriteria
        method: POST
        description: Create a Pipeline Run in the appropriate Pipeline based on the trigger and inputs.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: dry_run
          in: query
          type: boolean
          description: Optionally validate the request but do not persist the actual Pipeline Run.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-apps-appId-pipelines-pipelineId-runs
      path: /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs
      operations:
      - name: listpipelineruns
        method: GET
        description: List runs within a pipeline ordered newest to oldest.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createpipelinerun
        method: POST
        description: Create a run within a pipeline.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: dry_run
          in: query
          type: boolean
          description: Optionally validate the request but do not persist the actual Pipeline Run.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId
      path: /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs/{runId}
      operations:
      - name: getpipelinerun
        method: GET
        description: Get a run within an pipeline.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletepipelinerun
        method: DELETE
        description: Deleting a completed Run within a Pipeline.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-cancel
      path: /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs/{runId}/cancel
      operations:
      - name: cancelpipelinerun
        method: POST
        description: Cancel a Run within an Pipeline.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-jobs
      path: /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs/{runId}/jobs
      operations:
      - name: listpipelinejobs
        method: GET
        description: List the details of the jobs within a pipeline run.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-jobs-jobId
      path: /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs/{runId}/jobs/{jobId}
      operations:
      - name: getpipelinejob
        method: GET
        description: List the details of a Job including Step information
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-jobs-jobId-steps-stepIndex
      path: /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs/{runId}/jobs/{jobId}/steps/{stepIndex}/logs
      operations:
      - name: listpipelinesteplogs
        method: GET
        description: Get a page of log output for a given step within a job.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-restart
      path: /orgs/{orgId}/apps/{appId}/pipelines/{pipelineId}/runs/{runId}/restart
      operations:
      - name: restartpipelinerun
        method: POST
        description: Restart a Run within an Pipeline by cloning it with the same trigger and inputs.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: orgs-orgId-pipeline-runs
      path: /orgs/{orgId}/pipeline-runs
      operations:
      - name: listpipelinerunsbyorg
        method: GET
        description: List all pipeline runs within the Org ordered newest to oldest. This can be filtered by app, pipeline,
          and status.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    namespace: humanitec-pipelineruns-rest
    port: 8080
    description: REST adapter for Humanitec API — PipelineRuns. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/orgs/{orgid}/apps/{appid}/pipeline-runs
      name: orgs-orgid-apps-appid-pipeline-runs
      description: REST surface for orgs-orgId-apps-appId-pipeline-runs.
      operations:
      - method: POST
        name: createpipelinerunbytriggercriteria
        description: Create a Pipeline Run in the appropriate Pipeline based on the trigger and inputs.
        call: humanitec-pipelineruns.createpipelinerunbytriggercriteria
        with:
          dry_run: rest.dry_run
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/pipelines/{pipelineid}/runs
      name: orgs-orgid-apps-appid-pipelines-pipelineid-runs
      description: REST surface for orgs-orgId-apps-appId-pipelines-pipelineId-runs.
      operations:
      - method: GET
        name: listpipelineruns
        description: List runs within a pipeline ordered newest to oldest.
        call: humanitec-pipelineruns.listpipelineruns
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createpipelinerun
        description: Create a run within a pipeline.
        call: humanitec-pipelineruns.createpipelinerun
        with:
          dry_run: rest.dry_run
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/pipelines/{pipelineid}/runs/{runid}
      name: orgs-orgid-apps-appid-pipelines-pipelineid-runs-runid
      description: REST surface for orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId.
      operations:
      - method: GET
        name: getpipelinerun
        description: Get a run within an pipeline.
        call: humanitec-pipelineruns.getpipelinerun
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: deletepipelinerun
        description: Deleting a completed Run within a Pipeline.
        call: humanitec-pipelineruns.deletepipelinerun
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/pipelines/{pipelineid}/runs/{runid}/cancel
      name: orgs-orgid-apps-appid-pipelines-pipelineid-runs-runid-cancel
      description: REST surface for orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-cancel.
      operations:
      - method: POST
        name: cancelpipelinerun
        description: Cancel a Run within an Pipeline.
        call: humanitec-pipelineruns.cancelpipelinerun
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/pipelines/{pipelineid}/runs/{runid}/jobs
      name: orgs-orgid-apps-appid-pipelines-pipelineid-runs-runid-jobs
      description: REST surface for orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-jobs.
      operations:
      - method: GET
        name: listpipelinejobs
        description: List the details of the jobs within a pipeline run.
        call: humanitec-pipelineruns.listpipelinejobs
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/pipelines/{pipelineid}/runs/{runid}/jobs/{jobid}
      name: orgs-orgid-apps-appid-pipelines-pipelineid-runs-runid-jobs-jobid
      description: REST surface for orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-jobs-jobId.
      operations:
      - method: GET
        name: getpipelinejob
        description: List the details of a Job including Step information
        call: humanitec-pipelineruns.getpipelinejob
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/pipelines/{pipelineid}/runs/{runid}/jobs/{jobid}/steps/{stepindex}/logs
      name: orgs-orgid-apps-appid-pipelines-pipelineid-runs-runid-jobs-jobid-steps-stepindex
      description: REST surface for orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-jobs-jobId-steps-stepIndex.
      operations:
      - method: GET
        name: listpipelinesteplogs
        description: Get a page of log output for a given step within a job.
        call: humanitec-pipelineruns.listpipelinesteplogs
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/apps/{appid}/pipelines/{pipelineid}/runs/{runid}/restart
      name: orgs-orgid-apps-appid-pipelines-pipelineid-runs-runid-restart
      description: REST surface for orgs-orgId-apps-appId-pipelines-pipelineId-runs-runId-restart.
      operations:
      - method: POST
        name: restartpipelinerun
        description: Restart a Run within an Pipeline by cloning it with the same trigger and inputs.
        call: humanitec-pipelineruns.restartpipelinerun
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/orgs/{orgid}/pipeline-runs
      name: orgs-orgid-pipeline-runs
      description: REST surface for orgs-orgId-pipeline-runs.
      operations:
      - method: GET
        name: listpipelinerunsbyorg
        description: List all pipeline runs within the Org ordered newest to oldest. This can be filtered by app, pipeline,
          and status.
        call: humanitec-pipelineruns.listpipelinerunsbyorg
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: humanitec-pipelineruns-mcp
    port: 9090
    transport: http
    description: MCP adapter for Humanitec API — PipelineRuns. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: create-pipeline-run-appropriate-pipeline
      description: Create a Pipeline Run in the appropriate Pipeline based on the trigger and inputs.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-pipelineruns.createpipelinerunbytriggercriteria
      with:
        dry_run: tools.dry_run
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-runs-within-pipeline-ordered
      description: List runs within a pipeline ordered newest to oldest.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-pipelineruns.listpipelineruns
      outputParameters:
      - type: object
        mapping: $.
    - name: create-run-within-pipeline
      description: Create a run within a pipeline.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-pipelineruns.createpipelinerun
      with:
        dry_run: tools.dry_run
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-run-within-pipeline
      description: Get a run within an pipeline.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-pipelineruns.getpipelinerun
      outputParameters:
      - type: object
        mapping: $.
    - name: deleting-completed-run-within-pipeline
      description: Deleting a completed Run within a Pipeline.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: humanitec-pipelineruns.deletepipelinerun
      outputParameters:
      - type: object
        mapping: $.
    - name: cancel-run-within-pipeline
      description: Cancel a Run within an Pipeline.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-pipelineruns.cancelpipelinerun
      outputParameters:
      - type: object
        mapping: $.
    - name: list-details-jobs-within-pipeline
      description: List the details of the jobs within a pipeline run.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-pipelineruns.listpipelinejobs
      outputParameters:
      - type: object
        mapping: $.
    - name: list-details-job-including-step
      description: List the details of a Job including Step information
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-pipelineruns.getpipelinejob
      outputParameters:
      - type: object
        mapping: $.
    - name: get-page-log-output-given
      description: Get a page of log output for a given step within a job.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-pipelineruns.listpipelinesteplogs
      outputParameters:
      - type: object
        mapping: $.
    - name: restart-run-within-pipeline-cloning
      description: Restart a Run within an Pipeline by cloning it with the same trigger and inputs.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: humanitec-pipelineruns.restartpipelinerun
      outputParameters:
      - type: object
        mapping: $.
    - name: list-all-pipeline-runs-within
      description: List all pipeline runs within the Org ordered newest to oldest. This can be filtered by app, pipeline,
        and status.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: humanitec-pipelineruns.listpipelinerunsbyorg
      outputParameters:
      - type: object
        mapping: $.