Honeycomb Markers API

openapi: 3.1.0
info:
  title: Honeycomb Auth Markers API
  description: The Honeycomb API is a REST API that provides programmatic access to the Honeycomb observability platform. It enables developers to manage datasets and columns, configure SLOs and burn alerts, set up triggers and recipients, manage boards and markers, administer environments, API keys, and access auth, query annotations, calculated fields, marker settings, reporting, dataset definitions, and service maps.
  version: '1.0'
  contact:
    name: Honeycomb Support
    url: https://support.honeycomb.io
  termsOfService: https://www.honeycomb.io/terms-of-service
servers:
- url: https://api.honeycomb.io
  description: Honeycomb Production API
security:
- ApiKeyAuth: []
tags:
- name: Markers
  description: Manage markers that indicate points in time on graphs where notable events occurred such as deploys or outages.
paths:
  /1/markers/{datasetSlug}:
    get:
      operationId: listMarkers
      summary: List all markers
      description: Returns a list of all markers for the specified dataset.
      tags:
      - Markers
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      responses:
        '200':
          description: A list of markers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Marker'
        '401':
          description: Unauthorized
    post:
      operationId: createMarker
      summary: Create a marker
      description: Creates a new marker on the specified dataset to indicate a point in time where a notable event occurred.
      tags:
      - Markers
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkerCreateRequest'
      responses:
        '201':
          description: Marker created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marker'
        '401':
          description: Unauthorized
  /1/markers/{datasetSlug}/{markerId}:
    put:
      operationId: updateMarker
      summary: Update a marker
      description: Updates a marker's properties.
      tags:
      - Markers
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/markerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkerUpdateRequest'
      responses:
        '200':
          description: Marker updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marker'
        '401':
          description: Unauthorized
        '404':
          description: Marker not found
    delete:
      operationId: deleteMarker
      summary: Delete a marker
      description: Deletes a marker from the specified dataset.
      tags:
      - Markers
      parameters:
      - $ref: '#/components/parameters/datasetSlug'
      - $ref: '#/components/parameters/markerId'
      responses:
        '204':
          description: Marker deleted
        '401':
          description: Unauthorized
        '404':
          description: Marker not found
components:
  parameters:
    datasetSlug:
      name: datasetSlug
      in: path
      required: true
      description: The slug identifier for the dataset. Dataset names are case insensitive.
      schema:
        type: string
    markerId:
      name: markerId
      in: path
      required: true
      description: The unique identifier for the marker.
      schema:
        type: string
  schemas:
    MarkerUpdateRequest:
      type: object
      properties:
        start_time:
          type: integer
          description: Updated Unix timestamp in seconds for the marker start.
        end_time:
          type: integer
          description: Updated Unix timestamp in seconds for the marker end.
        message:
          type: string
          description: An updated message describing the marker event.
        type:
          type: string
          description: An updated type for the marker.
        url:
          type: string
          format: uri
          description: An updated URL associated with the marker event.
    Marker:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the marker.
        start_time:
          type: integer
          description: Unix timestamp in seconds for when the marker starts.
        end_time:
          type: integer
          description: Unix timestamp in seconds for when the marker ends. If omitted, the marker represents a single point in time.
        message:
          type: string
          description: A message describing the marker event.
        type:
          type: string
          description: The type of the marker, used to group related markers.
        url:
          type: string
          format: uri
          description: A URL associated with the marker event.
        created_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the marker was created.
        updated_at:
          type: string
          format: date-time
          description: ISO8601 formatted time the marker was last updated.
    MarkerCreateRequest:
      type: object
      properties:
        start_time:
          type: integer
          description: Unix timestamp in seconds for the marker start. Defaults to current time if not provided.
        end_time:
          type: integer
          description: Unix timestamp in seconds for the marker end.
        message:
          type: string
          description: A message describing the marker event.
        type:
          type: string
          description: The type of the marker, used to group related markers.
        url:
          type: string
          format: uri
          description: A URL associated with the marker event.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Honeycomb-Team
      description: Honeycomb Configuration API key. Must have appropriate permissions for the endpoint being called.
externalDocs:
  description: Honeycomb API Documentation
  url: https://api-docs.honeycomb.io/api