Honeycomb

Honeycomb Markers API

Annotate the Honeycomb timeline with Markers representing deploys, feature flag changes, incidents, or arbitrary externally meaningful events. Marker Settings define per-type appearance (colour, label) so deploy-vs-incident annotations render distinctly on every graph.

Honeycomb Markers API is one of 12 APIs that Honeycomb publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 2 machine-runnable capabilities that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Observability, Markers, Deployments, and Annotations. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 2 Naftiko capability specs.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.honeycomb.io/api/tag/Markers
📖
Documentation
https://docs.honeycomb.io/api/tag/Marker-Settings

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/honeycomb-io/refs/heads/main/openapi/honeycomb-markers-api-openapi.yml

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/honeycomb-io/refs/heads/main/capabilities/markers-markers.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/honeycomb-io/refs/heads/main/capabilities/markers-settings.yaml

OpenAPI Specification

honeycomb-markers-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Honeycomb Markers API
  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    email: [email protected]
  description: 'The API allows programmatic management of many resources within Honeycomb.


    Please report any discrepancies with actual API behavior in <a href="https://docs.honeycomb.io/troubleshoot/community/">Pollinators Slack</a> or to <a href="https://support.honeycomb.io/">Honeycomb
    Support</a>.

    '
externalDocs:
  url: https://docs.honeycomb.io
servers:
- url: https://api.honeycomb.io
- url: https://api.eu1.honeycomb.io
tags:
- name: Markers
  description: 'Markers indicate points in time on graphs where interesting things happen, such as deploys or outages.


    This API allows you to list, create, update, and delete Markers.


    ## Authorization


    The API key must have the **Manage Markers** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).

    '
- name: Marker Settings
  description: 'Marker Settings apply to groups of similar Markers.

    For example, "deploys" markers appear with the same color on a graph.


    This API allows you to list, create, update, and delete Marker Settings.


    ## Authorization


    The API key must have the **Manage Markers** permission. Learn more about [API keys here](https://docs.honeycomb.io/configure/environments/manage-api-keys/).

    '
paths:
  /1/markers/{datasetSlug}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    post:
      security:
      - configuration_key: []
      summary: Create a Marker
      description: 'Create a Marker in the specified dataset. To create an environment marker, use the `__all__` keyword and an API key associated with the desired environment.

        '
      tags:
      - Markers
      operationId: createMarker
      requestBody:
        description: 'The marker body can include as many of the Marker fields as desired.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Marker'
        required: true
      responses:
        '201':
          description: Created
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marker'
              example:
                created_at: '2016-08-13T05:39:42Z'
                updated_at: '2016-08-13T05:39:42Z'
                start_time: 1471040808
                message: 'backend deploy #123'
                type: deploy
                id: d1c84ec0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    get:
      security:
      - configuration_key: []
      summary: List All Markers
      description: 'Lists all Markers for a dataset.

        '
      tags:
      - Markers
      operationId: getMarker
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Marker'
              example:
              - created_at: '2016-08-13T05:39:42Z'
                updated_at: '2016-08-13T05:39:42Z'
                start_time: 1471040808
                message: 'backend deploy #123'
                type: deploy
                id: d1c84ec0
              - created_at: '2016-08-14T05:39:42Z'
                updated_at: '2016-08-14T05:39:42Z'
                start_time: 1471040808
                message: 'frontend deploy #123'
                type: deploy
                id: c2b52fa0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
  /1/markers/{datasetSlug}/{markerId}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    - name: markerId
      description: The unique identifier (ID) of a Marker.
      in: path
      required: true
      schema:
        type: string
    put:
      security:
      - configuration_key: []
      summary: Update a Marker
      description: 'Update a Marker in the specified dataset. To update an environment marker, use the `__all__` keyword and an API key associated with the desired environment.

        '
      tags:
      - Markers
      operationId: updateMarker
      requestBody:
        description: 'If an existing field is not included in the payload, it will be erased.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Marker'
        required: true
      responses:
        '200':
          description: Updated
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marker'
              example:
                created_at: '2016-08-13T05:39:42Z'
                updated_at: '2016-08-13T05:39:42Z'
                start_time: 1471040808
                message: 'backend deploy #123'
                type: deploy
                id: d1c84ec0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    delete:
      security:
      - configuration_key: []
      summary: Delete a Marker
      tags:
      - Markers
      operationId: deleteMarker
      responses:
        '200':
          description: 'Success

            The deleted Marker will be in the body of the response.

            '
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marker'
              example:
                created_at: '2016-08-13T05:39:42Z'
                updated_at: '2016-08-13T05:39:42Z'
                start_time: 1471040808
                message: 'backend deploy #123'
                type: deploy
                id: d1c84ec0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
  /1/marker_settings/{datasetSlug}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    post:
      security:
      - configuration_key: []
      summary: Create a Marker Setting
      tags:
      - Marker Settings
      operationId: createMarkerSetting
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkerSetting'
        required: true
      responses:
        '201':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkerSetting'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
    get:
      security:
      - configuration_key: []
      summary: Get a Marker Setting
      tags:
      - Marker Settings
      operationId: listMarkerSettings
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarkerSetting'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /1/marker_settings/{datasetSlug}/{markerSettingId}:
    parameters:
    - $ref: '#/components/parameters/datasetSlugOrAll'
    - name: markerSettingId
      description: The unique identifier (ID) of a marker setting.
      in: path
      required: true
      schema:
        type: string
    put:
      security:
      - configuration_key: []
      summary: Update a Marker Setting
      description: 'A marker setting''s `type` may not be changed after creation.

        '
      tags:
      - Marker Settings
      operationId: updateMarkerSettings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkerSetting'
            example:
              type: deploy
              color: '#1fa297'
        required: true
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkerSetting'
              example:
                type: deploy
                color: '#1fa297'
                id: gwAHiE5TS4j
                created_at: '2022-09-15T05:39:42Z'
                updated_at: '2022-12-20T08:10:05Z'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      security:
      - configuration_key: []
      summary: Delete a Marker Setting
      tags:
      - Marker Settings
      operationId: deleteMarkerSettings
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkerSetting'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unknown API key - check your credentials
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    ValidationFailed:
      description: Validation Failed
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            status: 422
            type: https://api.honeycomb.io/problems/validation-failed
            error: The provided input is invalid.
            title: The provided input is invalid
            type_detail:
            - field: type
              code: invalid
              description: 'type: must be a valid value'
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    GenericError:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: dataset not found
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 404
            type: https://api.honeycomb.io/problems/not-found
            title: The requested resource cannot be found.
            error: Dataset not found
            detail: Dataset not found
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    RateLimited:
      description: Rate Limit Exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limited
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            status: 429
            type: https://api.honeycomb.io/problems/rate-limited
            title: You have exceeded your rate limit.
            error: You have exceeded your rate limit.
            detail: Please try again after 2025-02-01T15:23:12Z.
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
          example:
            errors:
            - id: 06dcdd6508ca822f0e7e2bb4121c1f52
              code: rate-limited/may-retry
              title: request rate limit exceeded
              detail: Please try again after 2025-02-01T15:23:12Z.
  headers:
    RateLimit:
      description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"limit=X, remaining=Y, reset=Z\".\nWhere:\n  - X is the maximum number of requests\
        \ allowed in the window\n  - Y is the number of requests remaining in the window\n  - Z is the number of seconds until the limit resets\n"
      schema:
        type: string
      example: limit=100, remaining=50, reset=60
    RateLimitPolicy:
      description: "The (draft07) recommended header from the IETF on rate limiting.\nThe value of the header is formatted \"X;w=Y\".\nWhere:\n - X is the maximum number of requests allowed in a window\n\
        \ - Y is the size of the window in seconds\n"
      schema:
        type: string
      example: 100;w=60
    RetryAfter:
      description: 'The RFC7231 header used to indicate when a client should retry requests.

        '
      schema:
        type: string
      example: Fri, 22 Mar 2024 18:37:53 GMT
  schemas:
    Marker:
      type: object
      properties:
        start_time:
          type: integer
          description: Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives. Expressed in Unix Time.
          example: 1471040808
        end_time:
          type: integer
          description: Specifies end time, and allows a Marker to be recorded as representing a time range, such as a 5 minute deploy. Expressed in Unix Time.
          example: 1668453920
        message:
          type: string
          description: A message to describe this specific Marker.
          example: 'backend deploy #123'
        type:
          type: string
          description: Groups similar Markers. For example, `deploys`. All Markers of the same type appear with the same color on the graph. Refer to the [Marker Settings](/api/marker-settings/) API for
            altering the color of each type.
          example: deploy
        url:
          type: string
          description: A target for the marker. Clicking the marker text will take you to this URL.
          example: http://link-to-build.here
        id:
          type: string
          description: A 6 character hexadecimal string assigned on Marker creation.
          readOnly: true
        created_at:
          type: string
          description: The ISO8601-formatted time when the Marker was created.
          readOnly: true
        updated_at:
          type: string
          description: The ISO8601-formatted time when the Marker was updated.
          readOnly: true
        color:
          type: string
          description: Color can be assigned to Markers using the Marker Settings endpoint. This field will be populated when List All Markers is called.
          readOnly: true
    DetailedError:
      x-tags:
      - Errors
      description: An RFC7807 'Problem Detail' formatted error message.
      type: object
      required:
      - error
      - status
      - type
      - title
      properties:
        error:
          type: string
          readOnly: true
          default: something went wrong!
        status:
          type: number
          readOnly: true
          description: The HTTP status code of the error.
        type:
          type: string
          readOnly: true
          description: Type is a URI used to uniquely identify the type of error.
        title:
          type: string
          readOnly: true
          description: Title is a human-readable summary that explains the `type` of the problem.
        detail:
          type: string
          readOnly: true
          description: The general, human-readable error message.
        instance:
          type: string
          readOnly: true
          description: The unique identifier (ID) for this specific error.
    JSONAPIError:
      x-tags:
      - Errors
      type: object
      description: A JSONAPI-formatted error message.
      properties:
        errors:
          type: array
          items:
            type: object
            readOnly: true
            required:
            - id
            - code
            properties:
              id:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              code:
                type: string
                readOnly: true
              title:
                type: string
                readOnly: true
              detail:
                type: string
                readOnly: true
              source:
                type: object
                readOnly: true
                properties:
                  pointer:
                    type: string
                    readOnly: true
                  header:
                    type: string
                    readOnly: true
                  parameter:
                    type: string
                    readOnly: true
    ValidationError:
      x-tags:
      - Errors
      allOf:
      - $ref: '#/components/schemas/DetailedError'
      - type: object
        properties:
          status:
            type: number
            readOnly: true
            default: 422
          type:
            type: string
            readOnly: true
            default: https://api.honeycomb.io/problems/validation-failed
          title:
            type: string
            readOnly: true
            default: The provided input is invalid.
          type_detail:
            type: array
            items:
              type: object
              properties:
                field:
                  type: string
                  readOnly: true
                code:
                  type: string
                  readOnly: true
                  enum:
                  - invalid
                  - missing
                  - incorrect_type
                  - already_exists
                description:
                  type: string
                  readOnly: true
    MarkerSetting:
      type: object
      required:
      - type
      - color
      properties:
        type:
          type: string
          description: 'Groups similar Markers. For example, ''deploys''. All Markers of the same type appears with the same color on the graph.

            '
          example: deploy
        color:
          type: string
          description: 'Color to use for display of this marker type. Specified as hexadecimal RGB. For example, "#F96E11".

            '
          example: '#7b1fa2'
        id:
          type: string
          description: The unique identifier (ID) for the Marker Setting.
          readOnly: true
          example: gwAHiE5TS4j
        created_at:
          type: string
          description: The ISO8601-formatted time when the Marker Setting was created.
          readOnly: true
          example: '2022-09-15T05:39:42Z'
        updated_at:
          type:
          - 'null'
          - string
          description: The ISO8601-formatted time when the Marker Setting was updated.
          readOnly: true
          example: '2022-12-15T04:25:14Z'
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
  parameters:
    datasetSlugOrAll:
      name: datasetSlug
      description: 'The dataset slug or use `__all__` for endpoints that support environment-wide operations.

        '
      in: path
      required: true
      schema:
        type: string