openapi: 3.1.0
info:
  title: Zipkin API v2 Autocomplete Spans API
  description: Zipkin's v2 HTTP API for querying and collecting distributed traces. Provides endpoints for submitting spans, querying traces, looking up services and span names, and retrieving dependency links between services.
  version: 2.0.0
  contact:
    name: OpenZipkin
    url: https://zipkin.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:9411
  description: Default Zipkin server
tags:
- name: Spans
  description: Submit and query span names
paths:
  /api/v2/spans:
    get:
      operationId: getSpanNames
      summary: Zipkin Get Span Names
      description: Returns a list of span names for a given service.
      tags:
      - Spans
      parameters:
      - name: serviceName
        in: query
        required: true
        description: The service name to lookup span names for
        schema:
          type: string
      responses:
        '200':
          description: A list of span names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Bad request
    post:
      operationId: reportSpans
      summary: Zipkin Report Spans
      description: Uploads a list of spans encoded per content type. Accepted content types are application/json and application/x-protobuf.
      tags:
      - Spans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Span'
      responses:
        '202':
          description: Spans accepted
        '400':
          description: Bad request - spans were malformed
components:
  schemas:
    Span:
      type: object
      required:
      - traceId
      - id
      properties:
        traceId:
          type: string
          description: Unique 128-bit or 64-bit trace identifier, hex encoded
          pattern: ^[0-9a-f]{16,32}$
        parentId:
          type: string
          description: The parent span ID, hex encoded, absent if root span
          pattern: ^[0-9a-f]{16}$
        id:
          type: string
          description: Unique 64-bit span identifier, hex encoded
          pattern: ^[0-9a-f]{16}$
        kind:
          type: string
          description: The type of span
          enum:
          - CLIENT
          - SERVER
          - PRODUCER
          - CONSUMER
        name:
          type: string
          description: The logical operation this span represents
        timestamp:
          type: integer
          format: int64
          description: Epoch microseconds of the start of this span
        duration:
          type: integer
          format: int64
          description: Duration in microseconds of the critical path
        localEndpoint:
          $ref: '#/components/schemas/Endpoint'
        remoteEndpoint:
          $ref: '#/components/schemas/Endpoint'
        annotations:
          type: array
          description: Events that explain latency with a timestamp
          items:
            $ref: '#/components/schemas/Annotation'
        tags:
          type: object
          description: Key-value pairs providing additional context
          additionalProperties:
            type: string
        debug:
          type: boolean
          description: True if this span was sampled with debug flag
        shared:
          type: boolean
          description: True if this span ID is shared between client and server
    Endpoint:
      type: object
      description: The network context of a node in the service graph
      properties:
        serviceName:
          type: string
          description: Lower-case label of this node in the service graph
        ipv4:
          type: string
          description: IPv4 address
          format: ipv4
        ipv6:
          type: string
          description: IPv6 address
          format: ipv6
        port:
          type: integer
          description: Port number
          minimum: 0
          maximum: 65535
    Annotation:
      type: object
      required:
      - timestamp
      - value
      properties:
        timestamp:
          type: integer
          format: int64
          description: Epoch microseconds of this event
        value:
          type: string
          description: Event value, usually a short description