openapi: 3.0.3
info:
    title: Tekton Hub
    description: HTTP services for managing Tekton Hub
    version: "1.0"
servers:
    - url: https://api.hub.tekton.dev
paths:
    /:
        get:
            tags:
                - status
            summary: Status status
            description: Return status of the services
            operationId: status#Status
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/StatusResponseBody'
    /catalog/{catalogName}/error:
        get:
            tags:
                - catalog
            summary: CatalogError catalog
            description: List all errors occurred refreshing a catalog
            operationId: catalog#CatalogError
            parameters:
                - name: catalogName
                  in: path
                  description: Name of catalog
                  required: true
                  schema:
                    type: string
                    description: Name of catalog
                    example: tekton
                  example: tekton
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CatalogErrorResponseBody'
                "500":
                    description: 'internal-error: Internal Server Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
            security:
                - jwt_header_Authorization:
                    - catalog:refresh
    /catalog/{catalogName}/refresh:
        post:
            tags:
                - catalog
            summary: Refresh catalog
            description: Refresh a Catalog by it's name
            operationId: catalog#Refresh
            parameters:
                - name: catalogName
                  in: path
                  description: Name of catalog
                  required: true
                  schema:
                    type: string
                    description: Name of catalog
                    example: tekton
                  example: tekton
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Job'
                "404":
                    description: 'not-found: Resource Not Found Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "500":
                    description: 'internal-error: Internal Server Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
            security:
                - jwt_header_Authorization:
                    - catalog:refresh
    /catalog/refresh:
        post:
            tags:
                - catalog
            summary: RefreshAll catalog
            description: Refresh all catalogs
            operationId: catalog#RefreshAll
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Job'
                "500":
                    description: 'internal-error: Internal Server Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
            security:
                - jwt_header_Authorization:
                    - catalog:refresh
    /categories:
        get:
            tags:
                - category
            summary: list category
            description: List all categories along with their tags sorted by name
            operationId: category#list
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListResponseBody'
                "500":
                    description: 'internal-error: Internal Server Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
    /query:
        get:
            tags:
                - resource
            summary: Query resource
            description: Find resources by a combination of name, kind, catalog, categories, platforms and tags
            operationId: resource#Query
            parameters:
                - name: name
                  in: query
                  description: Name of resource
                  allowEmptyValue: true
                  schema:
                    type: string
                    description: Name of resource
                    default: ""
                    example: buildah
                  example: buildah
                - name: catalogs
                  in: query
                  description: Catalogs of resource to filter by
                  allowEmptyValue: true
                  schema:
                    type: array
                    items:
                        type: string
                    description: Catalogs of resource to filter by
                    example:
                        - tekton
                        - openshift
                  example:
                    - tekton
                    - openshift
                - name: categories
                  in: query
                  description: Category associated with a resource to filter by
                  allowEmptyValue: true
                  schema:
                    type: array
                    items:
                        type: string
                    description: Category associated with a resource to filter by
                    example:
                        - build
                        - tools
                  example:
                    - build
                    - tools
                - name: kinds
                  in: query
                  description: Kinds of resource to filter by
                  allowEmptyValue: true
                  schema:
                    type: array
                    items:
                        type: string
                    description: Kinds of resource to filter by
                    example:
                        - task
                        - pipelines
                  example:
                    - task
                    - pipelines
                - name: tags
                  in: query
                  description: Tags associated with a resource to filter by
                  allowEmptyValue: true
                  schema:
                    type: array
                    items:
                        type: string
                    description: Tags associated with a resource to filter by
                    example:
                        - image
                        - build
                  example:
                    - image
                    - build
                - name: platforms
                  in: query
                  description: Platforms associated with a resource to filter by
                  allowEmptyValue: true
                  schema:
                    type: array
                    items:
                        type: string
                    description: Platforms associated with a resource to filter by
                    example:
                        - linux/s390x
                        - linux/amd64
                  example:
                    - linux/s390x
                    - linux/amd64
                - name: limit
                  in: query
                  description: Maximum number of resources to be returned
                  allowEmptyValue: true
                  schema:
                    type: integer
                    description: Maximum number of resources to be returned
                    default: 1000
                    example: 100
                    format: int64
                  example: 100
                - name: match
                  in: query
                  description: Strategy used to find matching resources
                  allowEmptyValue: true
                  schema:
                    type: string
                    description: Strategy used to find matching resources
                    default: contains
                    enum:
                        - exact
                        - contains
            responses:
                "302":
                    description: Found response.
                    headers:
                        location:
                            description: Redirect URL
                            schema:
                                type: string
                                description: Redirect URL
                                format: uri
    /resource/{catalog}/{kind}/{name}:
        get:
            tags:
                - resource
            summary: ByCatalogKindName resource
            description: Find resources using name of catalog, resource name and kind of resource
            operationId: resource#ByCatalogKindName
            parameters:
                - name: pipelinesversion
                  in: query
                  description: To find resource compatible with a Tekton pipelines version, use this param
                  allowEmptyValue: true
                  schema:
                    type: string
                    description: To find resource compatible with a Tekton pipelines version, use this param
                    example: 0.21.0
                    pattern: ^\d+(?:\.\d+){0,2}$
                  example: 0.21.0
                - name: catalog
                  in: path
                  description: name of catalog
                  required: true
                  schema:
                    type: string
                    description: name of catalog
                    example: tektoncd
                  example: tektoncd
                - name: kind
                  in: path
                  description: kind of resource
                  required: true
                  schema:
                    type: string
                    description: kind of resource
                    enum:
                        - task
                        - pipeline
                - name: name
                  in: path
                  description: Name of resource
                  required: true
                  schema:
                    type: string
                    description: Name of resource
                    example: buildah
                  example: buildah
            responses:
                "302":
                    description: Found response.
                    headers:
                        location:
                            description: Redirect URL
                            schema:
                                type: string
                                description: Redirect URL
                                format: uri
    /resource/{catalog}/{kind}/{name}/{version}:
        get:
            tags:
                - resource
            summary: ByCatalogKindNameVersion resource
            description: Find resource using name of catalog & name, kind and version of resource
            operationId: resource#ByCatalogKindNameVersion
            parameters:
                - name: catalog
                  in: path
                  description: name of catalog
                  required: true
                  schema:
                    type: string
                    description: name of catalog
                    example: tektoncd
                  example: tektoncd
                - name: kind
                  in: path
                  description: kind of resource
                  required: true
                  schema:
                    type: string
                    description: kind of resource
                    enum:
                        - task
                        - pipeline
                - name: name
                  in: path
                  description: name of resource
                  required: true
                  schema:
                    type: string
                    description: name of resource
                    example: buildah
                  example: buildah
                - name: version
                  in: path
                  description: version of resource
                  required: true
                  schema:
                    type: string
                    description: version of resource
                    example: "0.1"
                  example: "0.1"
            responses:
                "302":
                    description: Found response.
                    headers:
                        location:
                            description: Redirect URL
                            schema:
                                type: string
                                description: Redirect URL
                                format: uri
    /resource/{id}:
        get:
            tags:
                - resource
            summary: ById resource
            description: Find a resource using it's id
            operationId: resource#ById
            parameters:
                - name: id
                  in: path
                  description: ID of a resource
                  required: true
                  schema:
                    type: integer
                    description: ID of a resource
                    example: 1
                    format: int64
                  example: 1
            responses:
                "302":
                    description: Found response.
                    headers:
                        location:
                            description: Redirect URL
                            schema:
                                type: string
                                description: Redirect URL
                                format: uri
    /resource/{id}/rating:
        get:
            tags:
                - rating
            summary: Get rating
            description: Find user's rating for a resource
            operationId: rating#Get
            parameters:
                - name: id
                  in: path
                  description: ID of a resource
                  required: true
                  schema:
                    type: integer
                    description: ID of a resource
                    format: int64
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetResponseBody'
                "401":
                    description: 'invalid-token: Invalid User token'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "403":
                    description: 'invalid-scopes: Invalid User scope'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "404":
                    description: 'not-found: Resource Not Found Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "500":
                    description: 'internal-error: Internal server error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
            security:
                - jwt_header_Authorization:
                    - rating:read
        put:
            tags:
                - rating
            summary: Update rating
            description: Update user's rating for a resource
            operationId: rating#Update
            parameters:
                - name: id
                  in: path
                  description: ID of a resource
                  required: true
                  schema:
                    type: integer
                    description: ID of a resource
                    format: int64
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateRequestBody'
            responses:
                "200":
                    description: OK response.
                "401":
                    description: 'invalid-token: Invalid User token'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "403":
                    description: 'invalid-scopes: Invalid User scope'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "404":
                    description: 'not-found: Resource Not Found Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "500":
                    description: 'internal-error: Internal server error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
            security:
                - jwt_header_Authorization:
                    - rating:write
    /resource/{id}/versions:
        get:
            tags:
                - resource
            summary: VersionsByID resource
            description: Find all versions of a resource by its id
            operationId: resource#VersionsByID
            parameters:
                - name: id
                  in: path
                  description: ID of a resource
                  required: true
                  schema:
                    type: integer
                    description: ID of a resource
                    example: 1
                    format: int64
                  example: 1
            responses:
                "302":
                    description: Found response.
                    headers:
                        location:
                            description: Redirect URL
                            schema:
                                type: string
                                description: Redirect URL
                                format: uri
    /resource/version/{versionID}:
        get:
            tags:
                - resource
            summary: ByVersionId resource
            description: Find a resource using its version's id
            operationId: resource#ByVersionId
            parameters:
                - name: versionID
                  in: path
                  description: Version ID of a resource's version
                  required: true
                  schema:
                    type: integer
                    description: Version ID of a resource's version
                    example: 1
                    format: int64
                  example: 1
            responses:
                "302":
                    description: Found response.
                    headers:
                        location:
                            description: Redirect URL
                            schema:
                                type: string
                                description: Redirect URL
                                format: uri
    /resources:
        get:
            tags:
                - resource
            summary: List resource
            description: List all resources sorted by rating and name
            operationId: resource#List
            responses:
                "301":
                    description: Moved Permanently response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Resources'
    /schema/swagger.json:
        get:
            tags:
                - swagger
            summary: Download docs/openapi3.json
            description: JSON document containing the API swagger definition
            operationId: swagger#/schema/swagger.json
            responses:
                "200":
                    description: File downloaded
    /system/config/refresh:
        post:
            tags:
                - admin
            summary: RefreshConfig admin
            description: Refresh the changes in config file
            operationId: admin#RefreshConfig
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RefreshConfigResponseBody'
                "401":
                    description: 'invalid-token: Invalid User token'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "403":
                    description: 'invalid-scopes: Invalid Token scopes '
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "500":
                    description: 'internal-error: Internal server error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
            security:
                - jwt_header_Authorization:
                    - config:refresh
    /system/user/agent:
        put:
            tags:
                - admin
            summary: UpdateAgent admin
            description: Create or Update an agent user with required scopes
            operationId: admin#UpdateAgent
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateAgentRequestBody'
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UpdateAgentResponseBody'
                "400":
                    description: 'invalid-payload: Invalid request body'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "401":
                    description: 'invalid-token: Invalid User token'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "403":
                    description: 'invalid-scopes: Invalid Token scopes '
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
                "500":
                    description: 'internal-error: Internal server error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
            security:
                - jwt_header_Authorization:
                    - agent:create
    /v1:
        get:
            tags:
                - status
            summary: Status status
            description: Return status of the services
            operationId: status#Status#1
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/StatusResponseBody'
    /v1/categories:
        get:
            tags:
                - category
            summary: list category
            description: List all categories along with their tags sorted by name
            operationId: category#list#1
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListResponseBody'
                "500":
                    description: 'internal-error: Internal Server Error'
                    content:
                        application/vnd.goa.error:
                            schema:
                                $ref: '#/components/schemas/Error'
components:
    schemas:
        Catalog:
            type: object
            properties:
                id:
                    type: integer
                    description: ID is the unique id of the catalog
                    example: 1
                    format: int64
                name:
                    type: string
                    description: Name of catalog
                    example: Tekton
                provider:
                    type: string
                    description: Provider of catalog
                    example: github
                type:
                    type: string
                    description: Type of catalog
                    example: community
                    enum:
                        - official
                        - community
                url:
                    type: string
                    description: URL of catalog
                    example: https://github.com/tektoncd/hub
            required:
                - id
                - name
                - type
                - url
                - provider
        CatalogErrorResponseBody:
            type: object
            properties:
                data:
                    type: array
                    items:
                        $ref: '#/components/schemas/CatalogErrors'
                    description: Catalog errors
            required:
                - data
        CatalogErrors:
            type: object
            properties:
                errors:
                    type: array
                    items:
                        type: string
                    description: Catalog Error message
                    example:
                        - Resource tekton.dev/v1beta1, Kind=Task - buildah has no display name
                        - Resource tekton.dev/v1beta1, Kind=task - curl has no display name
                type:
                    type: string
                    description: Catalog Errror type
                    example: warning
            description: CatalogErrors define the errors that occurred during catalog refresh
            required:
                - type
                - errors
        Category:
            type: object
            properties:
                id:
                    type: integer
                    description: ID is the unique id of the category
                    example: 1
                    format: int64
                name:
                    type: string
                    description: Name of category
                    example: Image Builder
            required:
                - id
                - name
        Error:
            type: object
            properties:
                fault:
                    type: boolean
                    description: Is the error a server-side fault?
                id:
                    type: string
                    description: ID is a unique identifier for this particular occurrence of the problem.
                    example: 123abc
                message:
                    type: string
                    description: Message is a human-readable explanation specific to this occurrence of the problem.
                    example: parameter 'p' must be an integer
                name:
                    type: string
                    description: Name is the name of this class of errors.
                    example: bad_request
                temporary:
                    type: boolean
                    description: Is the error temporary?
                timeout:
                    type: boolean
                    description: Is the error a timeout?
            description: Invalid request body
            required:
                - name
                - id
                - message
                - temporary
                - timeout
                - fault
        GetResponseBody:
            type: object
            properties:
                rating:
                    type: integer
                    description: User rating for resource
                    example: 4
                    format: int64
            required:
                - rating
        HubService:
            type: object
            properties:
                error:
                    type: string
                    description: Details of the error if any
                    example: unable to reach db
                name:
                    type: string
                    description: Name of the service
                    example: api
                status:
                    type: string
                    description: Status of the service
                    example: ok
                    enum:
                        - ok
                        - error
            description: Describes the services and their status
            required:
                - name
                - status
        Job:
            type: object
            properties:
                catalogName:
                    type: string
                    description: Name of the catalog
                    example: tekton
                id:
                    type: integer
                    description: id of the job
                    example: 1
                    format: int64
                status:
                    type: string
                    description: status of the job
                    example: queued
            required:
                - id
                - catalogName
                - status
        ListResponseBody:
            type: object
            properties:
                data:
                    type: array
                    items:
                        $ref: '#/components/schemas/Category'
        RefreshConfigResponseBody:
            type: object
            properties:
                checksum:
                    type: string
                    description: Config file checksum
                    example: 41ba391c8baf1fcd3c62c11272b913dc6613f4cf3b1833cfbb32431dc4384c93
            required:
                - checksum
        ResourceData:
            type: object
            properties:
                catalog:
                    $ref: '#/components/schemas/Catalog'
                categories:
                    type: array
                    items:
                        $ref: '#/components/schemas/Category'
                    description: Categories related to resource
                    example:
                        - id: 1
                          name: image-build
                hubRawURLPath:
                    type: string
                    description: Path of the api to get the raw yaml of resource from hub apiserver
                    example: /tekton/task/buildah/raw
                hubURLPath:
                    type: string
                    description: Url path of the resource in hub
                    example: tekton/task/buildah
                id:
                    type: integer
                    description: ID is the unique id of the resource
                    example: 1
                    format: int64
                kind:
                    type: string
                    description: Kind of resource
                    example: task
                latestVersion:
                    $ref: '#/components/schemas/ResourceVersionData'
                name:
                    type: string
                    description: Name of resource
                    example: buildah
                platforms:
                    type: array
                    items:
                        $ref: '#/components/schemas/Category'
                    description: Platforms related to resource
                    example:
                        - id: 1
                          name: linux/amd64
                rating:
                    type: number
                    description: Rating of resource
                    example: 4.3
                    format: double
                tags:
                    type: array
                    items:
                        $ref: '#/components/schemas/Category'
                    description: Tags related to resource
                    example:
                        - id: 1
                          name: image-build
                versions:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResourceVersionData'
                    description: List of all versions of a resource
                    example:
                        - id: 1
                          version: "0.1"
                        - id: 2
                          version: "0.2"
            description: The resource type describes resource information.
            required:
                - id
                - name
                - catalog
                - categories
                - kind
                - hubURLPath
                - latestVersion
                - tags
                - platforms
                - rating
                - versions
                - hubRawURLPath
        ResourceDataCollection:
            type: array
            items:
                $ref: '#/components/schemas/ResourceData'
        ResourceVersionData:
            type: object
            properties:
                deprecated:
                    type: boolean
                    description: Deprecation status of a version
                    example: true
                description:
                    type: string
                    description: Description of version
                    example: Buildah task builds source into a container image and then pushes it to a container registry.
                displayName:
                    type: string
                    description: Display name of version
                    example: Buildah
                hubRawURLPath:
                    type: string
                    description: Path of the api to get the raw yaml of resource from hub apiserver
                    example: /tekton/task/buildah/raw
                hubURLPath:
                    type: string
                    description: Url path of the resource in hub
                    example: tekton/task/buildah
                id:
                    type: integer
                    description: ID is the unique id of resource's version
                    example: 1
                    format: int64
                minPipelinesVersion:
                    type: string
                    description: Minimum pipelines version the resource's version is compatible with
                    example: 0.12.1
                platforms:
                    type: array
                    items:
                        $ref: '#/components/schemas/Category'
                    description: Platforms related to resource version
                    example:
                        - id: 1
                          name: linux/s390x
                rawURL:
                    type: string
                    description: Raw URL of resource's yaml file of the version
                    example: https://raw.githubusercontent.com/tektoncd/catalog/main/task/buildah/0.1/buildah.yaml
                    format: uri
                resource:
                    $ref: '#/components/schemas/ResourceData'
                updatedAt:
                    type: string
                    description: Timestamp when version was last updated
                    example: 2020-01-01 12:00:00 +0000 UTC
                    format: date-time
                version:
                    type: string
                    description: Version of resource
                    example: "0.1"
                webURL:
                    type: string
                    description: Web URL of resource's yaml file of the version
                    example: https://github.com/tektoncd/catalog/blob/main/task/buildah/0.1/buildah.yaml
                    format: uri
            description: The Version result type describes resource's version information.
            required:
                - id
                - version
                - displayName
                - description
                - minPipelinesVersion
                - rawURL
                - webURL
                - updatedAt
                - platforms
                - resource
                - hubURLPath
                - hubRawURLPath
        Resources:
            type: object
            properties:
                data:
                    $ref: '#/components/schemas/ResourceDataCollection'
            required:
                - data
        StatusResponseBody:
            type: object
            properties:
                services:
                    type: array
                    items:
                        $ref: '#/components/schemas/HubService'
                    description: List of services and their status
        UpdateAgentRequestBody:
            type: object
            properties:
                name:
                    type: string
                    description: Name of Agent
                    example: abc
                scopes:
                    type: array
                    items:
                        type: string
                    description: Scopes required for Agent
                    example:
                        - catalog-refresh
                        - agent:create
            required:
                - name
                - scopes
        UpdateAgentResponseBody:
            type: object
            properties:
                token:
                    type: string
                    description: Agent JWT
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Nzc4ODAzMDAsImlhdCI6MTU3Nzg4MDAwMCwiaWQiOjExLCJpc3MiOiJUZWt0b24gSHViIiwic2NvcGVzIjpbInJhdGluZzpyZWFkIiwicmF0aW5nOndyaXRlIiwiYWdlbnQ6Y3JlYXRlIl0sInR5cGUiOiJhY2Nlc3MtdG9rZW4ifQ.6pDmziSKkoSqI1f0rc4-AqVdcfY0Q8wA-tSLzdTCLgM
            required:
                - token
        UpdateRequestBody:
            type: object
            properties:
                rating:
                    type: integer
                    description: User rating for resource
                    format: int64
                    minimum: 0
                    maximum: 5
            required:
                - rating
    securitySchemes:
        jwt_header_Authorization:
            type: http
            description: Secures endpoint by requiring a valid JWT retrieved via the /auth/login endpoint.
            scheme: bearer
tags:
    - name: swagger
      description: The swagger service serves the API swagger definition.
    - name: admin
      description: Admin service
    - name: catalog
      description: The Catalog Service exposes endpoints to interact with catalogs
    - name: category
      description: The category service provides details about category
    - name: rating
      description: The rating service exposes endpoints to read and write user's rating for resources
    - name: resource
      description: The resource service provides details about all kind of resources
    - name: status
      description: Describes the status of each service
