Humanitec ArtefactVersion API
Details of a Container Artefact Version
OpenAPI Specification
openapi: 3.0.0
info:
title: Humanitec AccountType ArtefactVersion API
version: 0.28.24
description: '# Introduction
The *Humanitec API* allows you to automate and integrate Humanitec into your developer and operational workflows.
The API is a REST based API. It is based around a set of concepts:
* Core
* External Resources
* Sets and Deltas
## Authentication
Almost all requests made to the Humanitec API require Authentication. See our [Developer Docs on API Authentication](https://developer.humanitec.com/platform-orchestrator/reference/api-references/#authentication) for instructions.
## Content Types
The Humanitec API, unless explicitly specified, only accepts content types of `application/json` and will always return valid `application/json` or an empty response.
## Response Codes
### Success
Any response code in the `2xx` range should be regarded as success.
| **Code** | **Meaning** |
|----------|-------------------------------------|
| `200` | Success |
| `201` | Success, a new resource was created |
| `204` | Success, but no content in response |
_Note: We plan to simplify the interface by replacing 201 with 200 status codes._
### Failure
Any response code in the `4xx` range should be regarded as an error that can be rectified by the client. `5xx` error codes indicate errors that cannot be corrected by the client.
| **Code** | **Meaning** |
|----------|-----------------------------------------------------------------------------------------------------------------------|
| `400` | General error. (Body will contain details) |
| `401` | Attempt to access protected resource without `Authorization` Header. |
| `403` | The `Bearer` or `JWT` does not grant access to the requested resource. |
| `404` | Resource not found. |
| `405` | Method not allowed |
| `409` | Conflict. Usually indicated a resource with that ID already exists. |
| `422` | Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected. |
| `429` | Too many requests - request rate limit has been reached. |
| `500` | Internal Error. If it occurs repeatedly, contact support. |
'
contact:
name: Humanitec Support
email: support@humanitec.com
x-logo:
url: humanitec-logo.png
altText: Humanitec logo
servers:
- url: https://api.humanitec.io/
tags:
- name: ArtefactVersion
x-displayName: Artefact Version
description: 'Details of a Container Artefact Version
<SchemaDefinition schemaRef="#/components/schemas/ContainerArtefactVersion" />
'
paths:
/orgs/{orgId}/artefact-versions:
get:
tags:
- ArtefactVersion
summary: List all Artefacts Versions in the org.
description: Returns the Artefact Versions registered with your organization. If no elements are found, an empty list is returned.
operationId: listArtefactVersionsInOrg
parameters:
- name: orgId
in: path
description: The organization ID.
required: true
example: sample-org
schema:
type: string
- name: name
in: query
description: (Optional) Filter Artefact Versions by name.
example: registry.humanitec.io/public/sample-app
schema:
type: string
- name: reference
in: query
description: (Optional) Filter Artefact Versions by the reference to a Version of the same Artefact. This cannot be used together with `name`.
example: registry.humanitec.io/public/sample-app:v1@sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244
schema:
type: string
- name: archived
in: query
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 archived and non-archived Versions are returned.
example: false
schema:
type: boolean
- name: type
in: query
description: (Optional) Filter by artefact type.
example: containers
schema:
type: string
responses:
'200':
description: A list of Artefact Versions registered with your organization.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ArtefactVersion'
type: array
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
post:
tags:
- ArtefactVersion
summary: Register a new Artefact Version with your organization.
operationId: createArtefactVersion
parameters:
- name: orgId
in: path
description: The organization ID.
required: true
example: sample-org
schema:
type: string
- name: vcs
in: query
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 ref, if not empty, is checked to ensure that it has the prefix "refs/".
example: git
schema:
type: string
- name: dry_run
in: query
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 "application/x.workload-deployment-set+x-yaml", the generated deployment set will be returned.
example: false
schema:
type: boolean
- name: Accept
in: header
description: Indicates which content types the client is able to understand.
schema:
type: string
requestBody:
description: The data needed to register a new Artefact Version within the organization.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateArtefactVersion'
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateArtefactVersion'
responses:
'200':
description: An Artefact Version.
content:
application/json:
schema:
$ref: '#/components/schemas/ArtefactVersion'
application/x.workload-deployment-set+json:
schema:
$ref: '#/components/schemas/WorkloadArtefactVersionDeploymentSet'
application/x.workload-deployment-set+x-yaml:
schema:
$ref: '#/components/schemas/WorkloadArtefactVersionDeploymentSet'
'204':
description: The request was valid, but no Artefact Version was created.
'400':
description: Either one or more request body parameters are missing or invalid, or the requested payload is not provided or malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'401':
description: Request unauthorised.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/artefact-versions/{artefactVersionId}:
get:
tags:
- ArtefactVersion
summary: Get an Artefacts Versions.
description: Returns a specific Artefact Version.
operationId: getArtefactVersion
parameters:
- name: orgId
in: path
description: The organization ID.
required: true
example: sample-org
schema:
type: string
- name: artefactVersionId
in: path
description: The Artefact Version ID.
example: 662b80db-cc71-40cf-b601-08d57983f6e4
required: true
schema:
type: string
responses:
'200':
description: An Artefact Version.
content:
application/json:
schema:
$ref: '#/components/schemas/ArtefactVersion'
'400':
description: Malformed Artefact Version ID.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: Artefact Version not found.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/artefacts/{artefactId}/versions:
get:
tags:
- ArtefactVersion
summary: List all Artefact Versions of an Artefact.
description: Returns the Artefact Versions of a specified Artefact registered with your organization. If no elements are found, an empty list is returned.
operationId: listArtefactVersions
parameters:
- name: orgId
in: path
description: The organization ID.
required: true
example: sample-org
schema:
type: string
- name: artefactId
in: path
description: The Artefact ID.
example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29
required: true
schema:
type: string
- name: archived
in: query
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 archived and non-archived Versions are returned.
example: false
schema:
type: boolean
- name: reference
in: query
description: (Optional) Filter Artefact Versions by by name including a version or digest.
example: registry.humanitec.io/public/sample-app:v1@sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244
schema:
type: string
- name: limit
in: query
description: (Optional) Limit the number of versions returned by the endpoint.
example: 20
schema:
type: integer
responses:
'200':
description: Returns all Versions of the specified Artefact.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ArtefactVersion'
type: array
'400':
description: Invalid inputs provided.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: No Artefact with the supplied ID `artefactID` has been found within the organization.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/artefacts/{artefactId}/versions/{versionId}:
patch:
tags:
- ArtefactVersion
summary: Update Version of an Artefact.
description: Update the version of a specified Artefact registered with your organization".
operationId: patchArtefactVersion
parameters:
- name: orgId
in: path
description: The organization ID.
required: true
example: sample-org
schema:
type: string
- name: artefactId
in: path
description: The Artefact ID.
example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29
required: true
schema:
type: string
- name: versionId
in: path
description: The Version ID.
example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29
required: true
schema:
type: string
requestBody:
description: The Artefact Version Update Request. Only the field `archive` can be updated.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateArtefactVersionPayloadRequest'
responses:
'200':
description: The updated Artefact Version.
content:
application/json:
schema:
$ref: '#/components/schemas/ArtefactVersion'
'400':
description: One or more request parameters are missing or invalid, or the requested payload is not provided or malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'401':
description: Request unauthorised.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'403':
description: Update requested on a version of a builtin artefact.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: No Artefact with the supplied artefactId or no Artefact Version with the supplied versionId have been found within the organization.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/artefact-versions/convert-score:
post:
tags:
- ArtefactVersion
summary: Convert a Score specification, optional overrides, and extensions into the contents for a deployment set.
operationId: convertScoreToSet
parameters:
- name: orgId
in: path
description: The organization ID.
required: true
example: sample-org
schema:
type: string
requestBody:
description: The Score specification, optional overrides, and extensions.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertScoreToSetBody'
responses:
'200':
description: The deployment set contents.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkloadArtefactVersionDeploymentSet'
'400':
description: Either one or more request body parameters are missing or invalid, or the requested payload is not provided or malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
components:
schemas:
WorkloadArtefactVersionDeploymentSet:
description: Humanitec definition for a Workload Artefact.
required:
- modules
- shared
properties:
modules:
description: The set of workloads to add when deployed, the key is the name of the workload.
type: object
additionalProperties:
type: object
additionalProperties: true
shared:
description: The set of shared resources to depend on, the key is the resource identifier.
type: object
additionalProperties:
type: object
additionalProperties: true
CreateWorkloadArtefactVersion:
description: Details for creating a new Workload Artefact Version
allOf:
- $ref: '#/components/schemas/CreateArtefactVersionBase'
- required:
- spec
properties:
spec:
type: object
additionalProperties: true
description: A Json object containing the workload specification. Score v1b1 is expected.
example:
apiVersion: score.dev/v1b1
metadata:
name: hello-world
image:
type: string
description: An optional default image to assign to any containers in the workload that do not have an image set or whose image is '.'
example: busybox:latest
overrides:
type: object
additionalProperties: true
description: An optional Json object containing the workload overrides. Score v1b1 is expected.
example:
apiVersion: score.dev/v1b1
profile: humanitec/default-module
property_overrides:
type: object
additionalProperties: true
description: An optional set of path overrides that will be applied to the workload.
example:
containers.my-container.image: busybox:latest
containers.my-container.variables.DEBUG: null
resource_type_aliases:
type: object
additionalProperties:
type: string
description: An optional set of resource types overrides that will be applied in the deployment set.
example:
s3: my-org/s3
extensions:
$ref: '#/components/schemas/ScoreHumanitecExtensions'
HumanitecErrorResponse:
description: HumanitecError represents a standard Humanitec Error
properties:
details:
additionalProperties: true
type: object
description: (Optional) Additional information is enclosed here.
error:
type: string
example: API-000
description: A short code to help with error identification.
message:
type: string
example: Could not validate token
description: A Human readable message about the error.
required:
- error
- message
type: object
example:
error: API-000
message: Could not validate token.
CreateArtefactVersion:
description: The details of a new Artefact Version to register. The type field is required and dictates the type of Artefact to register.
type: object
required:
- type
properties:
type:
description: The Artefact Version type.
type: string
example: container
oneOf:
- $ref: '#/components/schemas/CreateContainerArtefactVersion'
- $ref: '#/components/schemas/CreateWorkloadArtefactVersion'
discriminator:
propertyName: type
mapping:
container: '#/components/schemas/CreateContainerArtefactVersion'
workload: '#/components/schemas/CreateWorkloadArtefactVersion'
UpdateArtefactVersionPayloadRequest:
description: UpdateArtefactVersionPayload contains the `archived` field that should be set in the Artefact Version to update.
properties:
archived:
description: The Value of the archived value.
example: true
nullable: true
type: boolean
required:
- archived
type: object
CreateArtefactVersionBase:
type: object
required:
- type
- name
properties:
type:
description: The Artefact Version type.
type: string
example: container
name:
description: The Artefact name.
type: string
example: registry.humanitec.io/my-org/my-service
version:
description: (Optional) The Artefact Version.
type: string
example: 1.2.7
ref:
description: (Optional) The ref the Artefact Version was built from.
type: string
example: refs/heads/main
commit:
description: (Optional) The commit ID the Artefact Version was built on.
pattern: ^[0-9a-f]{5,40}$
example: 884bccaa807ea27cc1997a7492a3b6279fd7bd55
type: string
ScoreHumanitecExtensions:
description: Humanitec workload extensions for the Workload Artefact Version. These can be used to override the profile, or workload module spec and resource attributes.
required:
- apiVersion
properties:
apiVersion:
description: The api version describing the format of the extensions.
type: string
profile:
description: An optional override for the workload profile
type: string
spec:
description: A map of additional workload spec fields that will be merged.
type: object
additionalProperties: true
deploy:
description: An optional deploy condition for the workload.
type: object
additionalProperties: false
properties:
when:
description: The stage the deployment should occur. "deploy", deployed in-parallel with other workloads (the default). "before", deployed before other workloads. "after", deployed after other workloads.
type: string
enum:
- before
- deploy
- after
example: before
success:
description: The success criteria for the deployment. "deploy", workload deployed. "available", workload available. "complete", workload complete (often used with jobs).
type: string
enum:
- deploy
- available
- complete
example: complete
timeout:
description: The timeout in seconds for the deployment to reach it's success condition.
type: integer
example:
apiVersion: humanitec.org/v1b1
profile: humanitec/default-module
spec:
labels:
my-label: my-value
ContainerArtefactVersion:
description: Details of a Container Artefact Version
allOf:
- $ref: '#/components/schemas/ArtefactVersionBase'
- required:
- ref
- commit
- digest
properties:
digest:
description: (Optional) The Artefact Version digest.
type: string
example: sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244
ArtefactVersion:
description: The details of an Artefact Version. The type field dictates the type of Artefact along with any additional fields.
type: object
required:
- type
properties:
type:
description: The Artefact Version type.
type: string
example: container
oneOf:
- $ref: '#/components/schemas/ContainerArtefactVersion'
- $ref: '#/components/schemas/WorkloadArtefactVersion'
discriminator:
propertyName: type
mapping:
container: '#/components/schemas/ContainerArtefactVersion'
workload: '#/components/schemas/WorkloadArtefactVersion'
ArtefactVersionBase:
type: object
required:
- type
- id
- name
- artefact_id
- archived
properties:
archived:
description: If the Artefact Version is archived.
example: false
type: boolean
artefact_id:
description: The UUID of the Artefact.
example: 01234567-89ab-cdef-0123-456789abcdef
type: string
commit:
description: (Optional) The commit ID the Artefact Version was built on.
example: 060c3d6530a881afb808f105f36af25e1ad1b2f3
type: string
created_at:
description: The time when the Artefact Version was added to Humanitec.
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
type: string
created_by:
description: The user ID of the user who added the Artefact Version to Humanitec.
example: 01234567-89ab-cdef-0123-456789abcdef
type: string
id:
description: The UUID of the Artefact Version.
example: 01234567-89ab-cdef-0123-456789abcdef
type: string
name:
description: The name of the Artefact.
example: registry.humanitec.io/my-org/my-service
type: string
ref:
description: (Optional) The ref the Artefact Version was built from.
example: refs/heads/main
type: string
updated_at:
description: The time when the Artefact Version was updated for the last time.
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
type: string
updated_by:
description: The user ID of the user who performed the last updated on the Artefact Version.
example: 01234567-89ab-cdef-0123-456789abcdef
type: string
version:
description: (Optional) The version of the Artefact Version.
example: 1.2.7
type: string
ConvertScoreToSetBody:
description: Request body for converting a Score manifest to Humanitec deployment set.
additionalProperties: false
required:
- spec
properties:
spec:
type: object
additionalProperties: true
description: A Json object containing the workload specification. Score v1b1 is expected.
example:
apiVersion: score.dev/v1b1
metadata:
name: hello-world
image:
type: string
description: An optional default image to assign to any containers in the workload that do not have an image set or whose image is '.'
example: busybox:latest
overrides:
type: object
additionalProperties: true
description: An optional Json object containing the workload overrides. Score v1b1 is expected.
example:
apiVersion: score.dev/v1b1
profile: humanitec/default-module
property_overrides:
type: object
additionalProperties: true
description: An optional set of path overrides that will be applied to the workload.
example:
containers.my-container.image: busybox:latest
containers.my-container.variables.DEBUG: null
resource_type_aliases:
type: object
additionalProperties:
type: string
description: An optional set of resource types overrides that will be applied in the deployment set.
example:
s3: my-org/s3
extensions:
$ref: '#/components/schemas/ScoreHumanitecExtensions'
CreateContainerArtefactVersion:
description: Details for creating a new Container Artefact Version
allOf:
- $ref: '#/components/schemas/CreateArtefactVersionBase'
- properties:
digest:
description: (Optional) The Artefact Version digest.
type: string
example: sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244
WorkloadArtefactVersion:
description: Details of a Workload Artefact Version
allOf:
- $ref: '#/components/schemas/ArtefactVersionBase'
- properties: {}
externalDocs:
description: Find out more about how to use Humanitec in your every-day development work.
url: https://developer.humanitec.com/
x-tagGroups:
- name: Core
tags:
- Agents
- Application
- Artefact
- ArtefactVersion
- AuditLogs
- Logs
- Deployment
- EnvironmentType
- Environment
- Image
- PublicKeys
- Organization
- Registry
- RuntimeInfo
- SecretStore
- Value
- ValueSetVersion
- name: App Configuration
tags:
- Delta
- Set
- WorkloadProfile
- name: Resources
tags:
- ActiveResource
- DriverDefinition
- MatchingCriteria
- ResourceDefinition
- ResourceDefinitionVersion
- ResourceProvision
- AccountType
- ResourceAccount
- ResourceType
- ResourceClass
- name: Automation
tags:
- AutomationRule
- Event
- Pipelines
- PipelineRuns
- PipelineApprovals
- name: Users
tags:
- UserProfile
- UserRole
- Group
- TokenInfo