Codefresh

Codefresh Annotations API

The Annotations API from Codefresh — 1 operation(s) for annotations.

Documentation GitHub OpenAPI

Operations 8

POST /annotations Create #

GET /annotations List #

DELETE /annotations Delete annotations #

PATCH /annotations/{id} Update annotation by ID #

DELETE /annotations/{id} Delete annotation by ID #

GET /annotations/keys List annotation keys #

GET /annotations/values/{key} List key annotation values #

POST /annotations/metadata Create many #

Specifications

⚙

OpenAPI

https://artifacts.apis.io/codefresh/openapi/codefresh-annotations-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/codefresh:codefresh-annotations-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  contact:
    name: Codefresh
    url: https://www.codefresh.io
  description: Codefresh API openAPI 3.0 specification
  termsOfService: https://codefresh.io/docs/docs/terms-and-privacy-policy/terms-of-service/
  title: Codefresh Annotations API
  version: 0.0.2
  x-logo:
    url: https://g.codefresh.io/modules/cf.resources/codefresh-api-docs-images/codefresh-logo-api.svg
    backgroundColor: '#FFFFFF'
    altText: Codefresh
servers:
- url: https://g.codefresh.io/api
security:
- API-key: []
tags:
- name: Annotations
  description: annotations
  x-id: annotations
paths:
  /annotations:
    post:
      x-action: createAnnotations
      x-entityId:
        pathId: body.entityId
        handlerName: getAnnotationKey
        pathName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  __v:
                    type: number
                  _id:
                    type: string
                  accountId:
                    type: string
                  entityId:
                    type: string
                  entityType:
                    type: string
                  key:
                    type: string
                  value:
                    type: string
                  type:
                    type: string
                type: object
          description: Annotation object
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotations-create
      requestBody:
        content:
          application/json:
            schema:
              properties:
                entityId:
                  type: string
                  description: Entity id
                entityType:
                  type: string
                  description: Entity type
                key:
                  type: string
                  description: Key of annotation
                value:
                  type: string
                  description: Value of annotation
                display:
                  type: string
                  description: Key of annotation to display, for builds annotation entityType
              type: object
        required: true
      summary: Create
      parameters: []
      x-sdk-interface: annotations.create
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X POST \\\n    -H \"Authorization: ${API_KEY}\" \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d \"{\\\"entityId\\\":\\\"${ENTITY_ID_STR}\\\",\\\"entityType\\\":\\\"${ENTITY_TYPE_STR}\\\",\\\"key\\\":\\\"${KEY_STR}\\\",\\\"value\\\":\\\"${VALUE_STR}\\\",\\\"display\\\":\\\"${DISPLAY_STR}\\\"}\" \\\n    \"https://g.codefresh.io/api/annotations\""
      - lang: node.js
        source: "sdk.annotations.create({\n    entityId: `${ENTITY_ID_STR}`,\n    entityType: `${ENTITY_TYPE_STR}`,\n    key: `${KEY_STR}`,\n    value: `${VALUE_STR}`,\n    display: `${DISPLAY_STR}`\n})"
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  properties:
                    __v:
                      type: number
                    _id:
                      type: string
                    accountId:
                      type: string
                    entityId:
                      type: string
                    entityType:
                      type: string
                    key:
                      type: string
                    value:
                      type: string
                    type:
                      type: string
                  type: object
                type: array
          description: Array of Annotations objects
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotations-list
      summary: List
      parameters:
      - description: id of annotation
        in: query
        name: id
        required: false
        schema:
          type: string
      - description: Entity id
        in: query
        name: entityId
        required: false
        schema:
          type: string
      - description: Entity type
        in: query
        name: entityType
        required: false
        schema:
          type: string
      - description: key of annotation
        in: query
        name: key
        required: false
        schema:
          type: string
      x-sdk-interface: annotations.list
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X GET \\\n    -H \"Authorization: ${API_KEY}\" \\\n    \"https://g.codefresh.io/api/annotations?id=${ID}&entityId=${ENTITY_ID}&entityType=${ENTITY_TYPE}&key=${KEY}\""
      - lang: node.js
        source: "sdk.annotations.list({\n    id,\n    entityId,\n    entityType,\n    key\n})"
    delete:
      x-action: deleteAnnotations
      x-entityId:
        pathId: query.entityId
        handlerName: getAnnotationKey
        pathName: query
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  n:
                    example: 2
                    type: integer
                  ok:
                    example: 1
                    type: integer
                type: object
          description: Result of deleting
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotations-delete
      summary: Delete annotations
      parameters:
      - description: id of annotation
        in: query
        name: id
        required: false
        schema:
          type: string
      - description: Entity id
        in: query
        name: entityId
        required: false
        schema:
          type: string
      - description: Entity type
        in: query
        name: entityType
        required: false
        schema:
          type: string
      - description: key of annotation
        in: query
        name: key
        required: false
        schema:
          type: string
      x-sdk-interface: annotations.delete
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X DELETE \\\n    -H \"Authorization: ${API_KEY}\" \\\n    \"https://g.codefresh.io/api/annotations?id=${ID}&entityId=${ENTITY_ID}&entityType=${ENTITY_TYPE}&key=${KEY}\""
      - lang: node.js
        source: "sdk.annotations.delete({\n    id,\n    entityId,\n    entityType,\n    key\n})"
  /annotations/{id}:
    patch:
      x-action: updateAnnotationById
      x-entityId: params.id
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  __v:
                    type: number
                  _id:
                    type: string
                  accountId:
                    type: string
                  entityId:
                    type: string
                  entityType:
                    type: string
                  key:
                    type: string
                  value:
                    type: string
                  type:
                    type: string
                type: object
          description: Annotation object
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotation-update-by-id
      requestBody:
        content:
          application/json:
            schema:
              properties:
                entityId:
                  type: string
                  description: Entity id
                entityType:
                  type: string
                  description: Entity type
                key:
                  type: string
                  description: Key of annotation
                value:
                  type: string
                  description: Value of annotation
                display:
                  type: string
                  description: Key of annotation to display, for builds annotation entityType
              type: object
        required: true
      summary: Update annotation by ID
      parameters:
      - description: ID of an object
        in: path
        name: id
        required: true
        schema:
          type: string
      x-sdk-interface: annotations.updateAnnotationById
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X PATCH \\\n    -H \"Authorization: ${API_KEY}\" \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d \"{\\\"entityId\\\":\\\"${ENTITY_ID_STR}\\\",\\\"entityType\\\":\\\"${ENTITY_TYPE_STR}\\\",\\\"key\\\":\\\"${KEY_STR}\\\",\\\"value\\\":\\\"${VALUE_STR}\\\",\\\"display\\\":\\\"${DISPLAY_STR}\\\"}\" \\\n    \"https://g.codefresh.io/api/annotations/${ID}\""
      - lang: node.js
        source: "sdk.annotations.updateAnnotationById({ id }, {\n    entityId: `${ENTITY_ID_STR}`,\n    entityType: `${ENTITY_TYPE_STR}`,\n    key: `${KEY_STR}`,\n    value: `${VALUE_STR}`,\n    display: `${DISPLAY_STR}`\n})"
    delete:
      x-action: deleteAnnotationById
      x-entityId: params.id
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  __v:
                    type: number
                  _id:
                    type: string
                  accountId:
                    type: string
                  entityId:
                    type: string
                  entityType:
                    type: string
                  key:
                    type: string
                  value:
                    type: string
                  type:
                    type: string
                type: object
          description: Annotation object
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotations-delete-by-id
      summary: Delete annotation by ID
      parameters:
      - description: ID of an object
        in: path
        name: id
        required: true
        schema:
          type: string
      x-sdk-interface: annotations.delete-by-id
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X DELETE \\\n    -H \"Authorization: ${API_KEY}\" \\\n    \"https://g.codefresh.io/api/annotations/${ID}\""
      - lang: node.js
        source: sdk.annotations.delete-by-id({ id })
  /annotations/keys:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
          description: Array of Annotations Keys
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotations-keys-list
      summary: List annotation keys
      parameters:
      - description: Entity type
        in: query
        name: entityType
        required: true
        schema:
          type: string
      - description: Should ignore data retention rate limit for workflow annotation type
        in: query
        name: ignoreBuildRetentionPolicy
        required: false
        schema:
          type: string
      x-sdk-interface: annotations.getAnnotationsKeys
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X GET \\\n    -H \"Authorization: ${API_KEY}\" \\\n    \"https://g.codefresh.io/api/annotations/keys?entityType=${ENTITY_TYPE}&ignoreBuildRetentionPolicy=${IGNORE_BUILD_RETENTION_POLICY}\""
      - lang: node.js
        source: sdk.annotations.getAnnotationsKeys({ entityType, ignoreBuildRetentionPolicy })
  /annotations/values/{key}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
          description: Array of Annotations Values
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotations-key-values-list
      summary: List key annotation values
      parameters:
      - description: Entity type
        in: query
        name: entityType
        required: true
        schema:
          type: string
      - description: key of annotation
        in: path
        name: key
        required: true
        schema:
          type: string
      - description: Should ignore data retention rate limit for workflow annotation type
        in: query
        name: ignoreBuildRetentionPolicy
        required: false
        schema:
          type: string
      x-sdk-interface: annotations.getAnnotationsValuesByKey
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X GET \\\n    -H \"Authorization: ${API_KEY}\" \\\n    \"https://g.codefresh.io/api/annotations/values/${KEY}?entityType=${ENTITY_TYPE}&ignoreBuildRetentionPolicy=${IGNORE_BUILD_RETENTION_POLICY}\""
      - lang: node.js
        source: sdk.annotations.getAnnotationsValuesByKey({ entityType, key, ignoreBuildRetentionPolicy })
  /annotations/metadata:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  set:
                    type: array
                    items:
                      type: object
                  unset:
                    type: array
                    items:
                      type: object
                type: object
          description: Annotation object
        '500':
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                  status:
                    example: Error
                    type: string
                type: object
          description: Error
      tags:
      - Annotations
      operationId: annotations-create-metadata
      requestBody:
        content:
          application/json:
            schema:
              properties:
                annotations:
                  type: object
                  properties:
                    set:
                      type: array
                      items:
                        type: object
                        properties:
                          entityId:
                            type: string
                            description: Entity id
                          entityType:
                            type: string
                            description: Entity type
                          annotations:
                            type: array
                            items:
                              type: object
                          display:
                            type: string
                            description: Key of annotation to display, for builds annotation entityType
                    unset:
                      type: array
                      items:
                        type: object
                        properties:
                          entityId:
                            type: string
                            description: Entity id
                          entityType:
                            type: string
                            description: Entity type
                          annotations:
                            type: array
                            items:
                              type: object
              type: object
        required: true
      summary: Create many
      parameters: []
      x-sdk-interface: annotations.createMany
      x-code-samples:
      - lang: curl
        source: "curl  \\\n    -X POST \\\n    -H \"Authorization: ${API_KEY}\" \\\n    -H 'Content-Type: application/json; charset=utf-8' \\\n    -d \"{\\\"annotations\\\":{\\\"set\\\":[{\\\"entityId\\\":\\\"${ENTITY_ID_STR}\\\",\\\"entityType\\\":\\\"${ENTITY_TYPE_STR}\\\",\\\"annotations\\\":[${ANNOTATIONS_ARR_OBJ}],\\\"display\\\":\\\"${DISPLAY_STR}\\\"}],\\\"unset\\\":[{\\\"entityId\\\":\\\"${ENTITY_ID_STR}\\\",\\\"entityType\\\":\\\"${ENTITY_TYPE_STR}\\\",\\\"annotations\\\":[${ANNOTATIONS_ARR_OBJ}]}]}}\" \\\n    \"https://g.codefresh.io/api/annotations/metadata\""
      - lang: node.js
        source: "sdk.annotations.createMany({\n    annotations: {\n        set: [\n            {\n                entityId: `${ENTITY_ID_STR}`,\n                entityType: `${ENTITY_TYPE_STR}`,\n                annotations: [\n                    { ...ANNOTATIONS_ARR_OBJ }\n                ],\n                display: `${DISPLAY_STR}`\n            }\n        ],\n        unset: [\n            {\n                entityId: `${ENTITY_ID_STR}`,\n                entityType: `${ENTITY_TYPE_STR}`,\n                annotations: [\n                    { ...ANNOTATIONS_ARR_OBJ }\n                ]\n            }\n        ]\n    }\n})"
components:
  securitySchemes:
    API-key:
      in: header
      name: Authorization
      description: 'An api key got from: User Settings -> API keys -> Generate'
      type: apiKey
x-service-name: api-public
x-base-path: /api
x-internal-services:
- pipeline-manager
- api
x-endpoint-conditions:
- weight: 0
  condition: global.has-general-service-role
  handlerRegex: (.*)
- weight: 1
  condition: global.has-kubernetes-endpoints-service-role
  handlerRegex: kubernetes\.\w+
- weight: 2
  condition: global.has-auth-service-role
  handlerRegex: api-key\.\w+
x-tagGroups:
- name: Pipelines / Builds
  tags:
  - Annotations
  - Builds
  - Execution Contexts
  - Images
  - Pipelines
  - Progress
  - Projects
  - Step-types
  - Triggers
  - Triggers Events
  - Triggers Types
- name: Kubernetes / Helm
  tags:
  - Environments V2
  - Helm Boards
  - Helm Charts
  - Helm Releases
  - Helm Sections
  - Kubernetes
- name: Swarm
  tags:
  - Compositions
  - Environments
- name: Integrations / Contexts
  tags:
  - Clusters
  - Contexts
  - Helm Cluster Configs
  - Helm Repos
  - Registries
  - Repos
- name: Account Management
  tags:
  - Abac
  - Accounts
  - Agents
  - Audit
  - Runtime Environments
  - Teams
  - Tokens
  - Views
- name: User Properties
  tags:
  - favorites
- name: On-Premise
  tags:
  - Features
  - Runtime Environments (Account)
  - Runtime Environments (Plan)
  - Runtime Environments (System)
  - Runtime Environments.
- name: Platform Analytics
  tags:


# --- truncated at 32 KB (145 KB total) ---
# Full source: https://artifacts.apis.io/codefresh/openapi/codefresh-annotations-api-openapi.yml