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.
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: support@honeycomb.io
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