honeycomb Service Maps API

openapi: 3.2.0
info:
  title: Honeycomb Service Maps API
  version: '1.0'
  description: 'Operations tagged Service Maps across 2 of this provider''s published API definitions: honeycomb-api-openapi.yml, honeycomb-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.honeycomb.io
  description: Honeycomb Production API
- url: https://api.eu1.honeycomb.io
tags:
- name: Service Maps
  description: Visualize relationships between services using dependency requests.
paths:
  /1/service_map:
    post:
      operationId: createServiceMapRequest
      summary: Create a service map dependency request
      description: Creates a new dependency request to generate a service map visualizing relationships between services.
      tags:
      - Service Maps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceMapRequest'
      responses:
        '201':
          description: Service map request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMapResult'
        '401':
          description: Unauthorized
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.honeycomb.io
      description: Honeycomb Production API
  /1/maps/dependencies/requests:
    post:
      security:
      - configuration_key: []
      summary: Create a Map Dependency Request
      description: Create a Map Dependency Request.
      tags:
      - Service Maps
      operationId: createMapDependencyRequest
      parameters:
      - name: limit
        in: query
        required: false
        description: 'Maximum number of dependencies to return. Default is 10000, maximum is 64000.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 64000
          default: 10000
        example: 5000
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMapDependenciesRequest'
            examples:
              Get all depenedencies for last 2 hours for the user-service:
                value:
                  time_range: 7200
                  filters:
                  - name: user-service
                    type: service
              Get dependencies for last 1 day starting from 2025-07-01:
                value:
                  time_range: 86400
                  start_time: 1751328000
        required: false
      responses:
        '200':
          description: Success - Results are ready or request has failed (see `status` field)
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
            Location:
              schema:
                type: string
              description: The Location header will contain the URL where the results can be fetched.
              example: https://api.honeycomb.io/1/maps/dependencies/requests/HprJhV1fYyr
            Last-Modified:
              schema:
                type: string
              description: The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMapDependenciesResponse'
        '201':
          description: Created - Request is pending
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
            Location:
              schema:
                type: string
              description: The Location header will contain the URL where the results can be fetched.
              example: https://api.honeycomb.io/1/maps/dependencies/requests/HprJhV1fYyr
            Last-Modified:
              schema:
                type: string
              description: The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMapDependenciesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    servers:
    - url: https://api.honeycomb.io
    - url: https://api.eu1.honeycomb.io
  /1/maps/dependencies/requests/{requestId}:
    parameters:
    - name: requestId
      description: The unique identifier (ID) of a Map Dependencies Request.
      in: path
      required: true
      schema:
        type: string
    get:
      security:
      - configuration_key: []
      summary: Get Map Dependencies
      description: 'Get the dependencies for a previously created Map Dependencies Request. Note: This endpoint returns a single page of results and uses pagination. Even if you specified a large limit in the initial POST request, you will receive up to the page size limit per request and must use the pagination links to retrieve additional results.'
      tags:
      - Service Maps
      operationId: getMapDependencies
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationSize'
      responses:
        '200':
          description: Success
          headers:
            Ratelimit:
              $ref: '#/components/headers/RateLimit'
            RateLimitPolicy:
              $ref: '#/components/headers/RateLimitPolicy'
            Last-Modified:
              schema:
                type: string
              description: The Last-Modified response HTTP header contains a date and time when the origin server believes the resource was last modified.
            Cache-Control:
              schema:
                type: string
              description: Cache-Control header is set for ready responses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMapDependenciesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        default:
          $ref: '#/components/responses/GenericError'
    servers:
    - url: https://api.honeycomb.io
    - url: https://api.eu1.honeycomb.io
components:
  schemas:
    ServiceMapResult:
      type: object
      properties:
        services:
          type: array
          description: List of services in the service map.
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the service.
        dependencies:
          type: array
          description: List of dependencies between services.
          items:
            type: object
            properties:
              source:
                type: string
                description: The source service name.
              target:
                type: string
                description: The target service name.
    ServiceMapRequest:
      type: object
      properties:
        time_range:
          type: integer
          description: The time range in seconds to generate the service map for.
        start_time:
          type: integer
          description: Unix timestamp for the service map start time.
        end_time:
          type: integer
          description: Unix timestamp for the service map end time.
        dataset:
          type: string
          description: The dataset slug to generate the service map from.
    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.
    MapNode:
      type: object
      description: A node in the service map (typically a service).
      required:
      - name
      properties:
        name:
          type: string
          description: 'Name of the service or node.

            '
          example: user-service
        type:
          type: string
          description: 'Type of the node. Currently only "service" is supported. Defaults to "service" if not specified.

            '
          enum:
          - service
          example: service
    CreateMapDependenciesResponse:
      type: object
      description: Response for a Map Dependency Request.
      properties:
        request_id:
          type: string
          description: 'Unique identifier for the Map Dependency Request.

            '
          example: abc123
        status:
          type: string
          description: 'Status of the Map Dependency Request.

            '
          enum:
          - pending
          - ready
          - error
          example: pending
    Error:
      x-tags:
      - Errors
      type: object
      description: A legacy error, containing only a textual description.
      properties:
        error:
          type: string
          readOnly: true
    GetMapDependenciesResponse:
      type: object
      description: Response containing map dependencies data.
      properties:
        request_id:
          type: string
          description: 'Unique identifier for the Map Dependency Request.

            '
          example: abc123
        status:
          type: string
          description: 'Status of the Map Dependency Request.

            '
          enum:
          - pending
          - ready
          - error
          example: ready
        dependencies:
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/MapDependency'
          - type: 'null'
          description: 'Array of service dependencies. Null when status is "pending" or "error".

            '
        links:
          $ref: '#/components/schemas/PaginationLinks'
    CreateMapDependenciesRequest:
      type: object
      description: Create a Map Dependency Request.
      properties:
        start_time:
          type: integer
          description: 'Absolute start time to evaluate dependencies, in seconds since UNIX epoch. Must be <= `end_time` (when `time_range` is not provided).

            '
          example: 1622548800
        end_time:
          type: integer
          description: 'Absolute end time to evaluate dependencies, in seconds since UNIX epoch. Must be >= `start_time` (when `time_range` is not provided).

            '
          example: 1622635200
        time_range:
          type: integer
          default: 7200
          minimum: 1
          description: 'Time range in seconds (minimum 1). Can be used with either `start_time` (seconds after `start_time`), `end_time` (seconds before `end_time`), or without either (seconds before now).

            '
          example: 7200
        filters:
          type: array
          description: 'Optional list of service nodes to filter dependencies by. Only dependencies involving these nodes will be returned.

            '
          items:
            $ref: '#/components/schemas/MapNode'
    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
    PaginationLinks:
      type: object
      description: Links to iterate through the pages of results.
      required:
      - next
      properties:
        next:
          type:
          - string
          - 'null'
          description: The URL for the next page of results.
          readOnly: true
          example: /2/teams/my-team/api-keys?page[after]=3025fa645ad1100d&page[size]=10
    MapDependency:
      type: object
      description: A dependency relationship between two services.
      properties:
        parent_node:
          $ref: '#/components/schemas/MapNode'
        child_node:
          $ref: '#/components/schemas/MapNode'
        call_count:
          type: integer
          description: 'Number of calls between the parent and child services.

            '
          example: 142
  parameters:
    PaginationSize:
      name: page[size]
      description: The number of entries to include per response. Maximum value is 100.
      in: query
      schema:
        type: number
        minimum: 1
        maximum: 100
        default: 20
      example: 10
    PaginationCursor:
      name: page[after]
      description: 'The string value of the `next` attribute from a previous result page.

        The cursor value must be empty or omitted for the first request of a cursor-paginated query.

        '
      in: query
      schema:
        type: string
      example: eyxJjcmAVhdGVkX
  responses:
    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'
    GenericError:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    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.
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            deny-management-apis:
              description: Team cannot access management APIs.
              value:
                error: Your team has been denied access to Management APIs, please contact support to be unblocked.
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
    BadRequest:
      description: The provided request body was invalid.
      headers:
        Ratelimit:
          $ref: '#/components/headers/RateLimit'
        RateLimitPolicy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          examples:
            DetailedError:
              value:
                status: 400
                type: https://api.honeycomb.io/problems/unparseable
                title: The request body could not be parsed.
                error: invalid gzip data
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            GenericError:
              value:
                error: invalid Query data
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/JSONAPIError'
          examples:
            JSONAPIError:
              value:
                errors:
                - id: 06dcdd6508ca822f0e7e2bb4121c1f52
                  code: invalid
                  title: request body could not be parsed
                  detail: invalid gzip data
    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'
  headers:
    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
    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
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Honeycomb-Team
      description: Honeycomb Configuration API key. Must have appropriate permissions for the endpoint being called.
    configuration_key:
      type: apiKey
      name: X-Honeycomb-Team
      in: header
      description: 'Authenticate using a Honeycomb Configuration Key.


        Pass the **Token** in the `X-Honeycomb-Team` header:

        ```http

        X-Honeycomb-Team: 1234567890123456789012

        ```


        If you created your key using the API, use `data.attributes.secret`; this is the same value as the **Token** in the UI.


        To learn how to create a Configuration Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    ingest_key:
      type: apiKey
      name: X-Honeycomb-Team
      in: header
      description: 'Authenticate using a Honeycomb Ingest Key.


        Pass the Ingest Key in the `X-Honeycomb-Team` header:

        ```http

        X-Honeycomb-Team: hc[x]ik_1234567890123456789012345612345678901234567890123456789012

        ```


        The key value is the key ID and key secret concatenated with no separator:

        - If you created your key through the UI, Honeycomb provides the complete value as the **Ingest Key**.

        - If you created your key using the API, construct the key value by concatenating `data.id` and `data.attributes.secret` with no separator.


        To learn how to create an Ingest Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    firehose_access_key:
      type: apiKey
      name: X-Amz-Firehose-Access-Key
      in: header
      description: 'We recommend using a Honeycomb Ingest Key to authenticate, though a Configuration Key will work.


        To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate using a Honeycomb Management Key.


        Pass the Management Key as a Bearer token in the `Authorization` header:

        ```http

        Authorization: Bearer hcxmk_12345678901234567890123456:12345678901234567890123456789012

        ```


        Construct the key value by joining the **Key ID** and **Secret** with a colon (`:`).


        To learn how to create a Management Key, visit [Manage Team API Keys](/configure/teams/manage-api-keys). To learn more about authenticating requests, visit [API Authentication](/api/authentication).

        '
      bearerFormat: HONEYCOMB_KEY_ID:HONEYCOMB_KEY_SECRET
x-refined-from:
- honeycomb-api-openapi.yml
- honeycomb-openapi.yml