openapi: 3.0.3
info:
  description: Coderd is the service created by running coder server. It is a thin API that connects workspaces, provisioners and users. coderd stores its state in Postgres and is the only service that communicates with Postgres.
  title: Coder Agents Debug API
  termsOfService: https://coder.com/legal/terms-of-service
  contact:
    name: API Support
    url: https://coder.com
    email: support@coder.com
  license:
    name: AGPL-3.0
    url: https://github.com/coder/coder/blob/main/LICENSE
  version: '2.0'
servers:
- url: https://{coderHost}/api/v2
  description: Coder instance
  variables:
    coderHost:
      default: coder.example.com
      description: Your Coder deployment hostname
security:
- CoderSessionToken: []
tags:
- name: Debug
paths:
  /api/v2/debug/coordinator:
    get:
      operationId: debug-info-wireguard-coordinator
      summary: Debug Info Wireguard Coordinator
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/derp/traffic:
    get:
      operationId: debug-derp-traffic
      summary: Debug DERP traffic
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/derp.BytesSentRecv'
  /api/v2/debug/expvar:
    get:
      operationId: debug-expvar
      summary: Debug expvar
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/v2/debug/health:
    get:
      operationId: debug-info-deployment-health
      summary: Debug Info Deployment Health
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      parameters:
      - name: force
        in: query
        required: false
        description: Force a healthcheck to run
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthsdk.HealthcheckReport'
  /api/v2/debug/health/settings:
    get:
      operationId: get-health-settings
      summary: Get health settings
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthsdk.HealthSettings'
    put:
      operationId: update-health-settings
      summary: Update health settings
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/healthsdk.UpdateHealthSettings'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthsdk.UpdateHealthSettings'
  /api/v2/debug/metrics:
    get:
      operationId: debug-metrics
      summary: Debug metrics
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/pprof:
    get:
      operationId: debug-pprof-index
      summary: Debug pprof index
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/pprof/cmdline:
    get:
      operationId: debug-pprof-cmdline
      summary: Debug pprof cmdline
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/pprof/profile:
    get:
      operationId: debug-pprof-profile
      summary: Debug pprof profile
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/pprof/symbol:
    get:
      operationId: debug-pprof-symbol
      summary: Debug pprof symbol
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/pprof/trace:
    get:
      operationId: debug-pprof-trace
      summary: Debug pprof trace
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/profile:
    post:
      operationId: collect-debug-profiles
      summary: Collect debug profiles
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/tailnet:
    get:
      operationId: debug-info-tailnet
      summary: Debug Info Tailnet
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '200':
          description: OK
  /api/v2/debug/ws:
    get:
      operationId: debug-info-websocket-test
      summary: Debug Info Websocket Test
      tags:
      - Debug
      security:
      - CoderSessionToken: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Response'
components:
  schemas:
    healthsdk.WorkspaceProxyReport:
      type: object
      properties:
        dismissed:
          type: boolean
        error:
          type: string
        healthy:
          type: boolean
          description: Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead.
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
        workspace_proxies:
          $ref: '#/components/schemas/codersdk.RegionsResponse-codersdk_WorkspaceProxy'
    codersdk.ProxyHealthReport:
      type: object
      properties:
        errors:
          type: array
          description: Errors are problems that prevent the workspace proxy from being healthy
          items:
            type: string
        warnings:
          type: array
          description: 'Warnings do not prevent the workspace proxy from being healthy, but

            should be addressed.'
          items:
            type: string
    healthsdk.WebsocketReport:
      type: object
      properties:
        body:
          type: string
        code:
          type: integer
        dismissed:
          type: boolean
        error:
          type: string
        healthy:
          type: boolean
          description: Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead.
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    codersdk.ProvisionerDaemon:
      type: object
      properties:
        api_version:
          type: string
        created_at:
          type: string
          format: date-time
        current_job:
          $ref: '#/components/schemas/codersdk.ProvisionerDaemonJob'
        id:
          type: string
          format: uuid
        key_id:
          type: string
          format: uuid
        key_name:
          type: string
          description: Optional fields.
        last_seen_at:
          type: string
          format: date-time
        name:
          type: string
        organization_id:
          type: string
          format: uuid
        previous_job:
          $ref: '#/components/schemas/codersdk.ProvisionerDaemonJob'
        provisioners:
          type: array
          items:
            type: string
        status:
          enum:
          - offline
          - idle
          - busy
          allOf:
          - $ref: '#/components/schemas/codersdk.ProvisionerDaemonStatus'
        tags:
          type: object
          additionalProperties:
            type: string
        version:
          type: string
    healthsdk.STUNReport:
      type: object
      properties:
        canSTUN:
          type: boolean
        enabled:
          type: boolean
        error:
          type: string
    healthsdk.DERPRegionReport:
      type: object
      properties:
        error:
          type: string
        healthy:
          type: boolean
          description: Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead.
        node_reports:
          type: array
          items:
            $ref: '#/components/schemas/healthsdk.DERPNodeReport'
        region:
          $ref: '#/components/schemas/tailcfg.DERPRegion'
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    healthsdk.DatabaseReport:
      type: object
      properties:
        dismissed:
          type: boolean
        error:
          type: string
        healthy:
          type: boolean
          description: Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead.
        latency:
          type: string
        latency_ms:
          type: integer
        reachable:
          type: boolean
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        threshold_ms:
          type: integer
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    codersdk.ProxyHealthStatus:
      type: string
      enum:
      - ok
      - unreachable
      - unhealthy
      - unregistered
    key.NodePublic:
      type: object
    healthsdk.ProvisionerDaemonsReport:
      type: object
      properties:
        dismissed:
          type: boolean
        error:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/healthsdk.ProvisionerDaemonsReportItem'
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    codersdk.ProvisionerDaemonStatus:
      type: string
      enum:
      - offline
      - idle
      - busy
    healthsdk.AccessURLReport:
      type: object
      properties:
        access_url:
          type: string
        dismissed:
          type: boolean
        error:
          type: string
        healthy:
          type: boolean
          description: Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead.
        healthz_response:
          type: string
        reachable:
          type: boolean
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        status_code:
          type: integer
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    codersdk.RegionsResponse-codersdk_WorkspaceProxy:
      type: object
      properties:
        regions:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceProxy'
    healthsdk.ProvisionerDaemonsReportItem:
      type: object
      properties:
        provisioner_daemon:
          $ref: '#/components/schemas/codersdk.ProvisionerDaemon'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    codersdk.ProvisionerJobStatus:
      type: string
      enum:
      - pending
      - running
      - succeeded
      - canceling
      - canceled
      - failed
      - unknown
    codersdk.WorkspaceProxy:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        deleted:
          type: boolean
        derp_enabled:
          type: boolean
        derp_only:
          type: boolean
        display_name:
          type: string
        healthy:
          type: boolean
        icon_url:
          type: string
        id:
          type: string
          format: uuid
        name:
          type: string
        path_app_url:
          type: string
          description: 'PathAppURL is the URL to the base path for path apps. Optional

            unless wildcard_hostname is set.

            E.g. https://us.example.com'
        status:
          description: 'Status is the latest status check of the proxy. This will be empty for deleted

            proxies. This value can be used to determine if a workspace proxy is healthy

            and ready to use.'
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceProxyStatus'
        updated_at:
          type: string
          format: date-time
        version:
          type: string
        wildcard_hostname:
          type: string
          description: 'WildcardHostname is the wildcard hostname for subdomain apps.

            E.g. *.us.example.com

            E.g. *--suffix.au.example.com

            Optional. Does not need to be on the same domain as PathAppURL.'
    derp.BytesSentRecv:
      type: object
      properties:
        key:
          description: Key is the public key of the client which sent/received these bytes.
          allOf:
          - $ref: '#/components/schemas/key.NodePublic'
        recv:
          type: integer
          format: int64
        sent:
          type: integer
          format: int64
    codersdk.ProvisionerDaemonJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          enum:
          - pending
          - running
          - succeeded
          - canceling
          - canceled
          - failed
          allOf:
          - $ref: '#/components/schemas/codersdk.ProvisionerJobStatus'
        template_display_name:
          type: string
        template_icon:
          type: string
        template_name:
          type: string
    healthsdk.DERPHealthReport:
      type: object
      properties:
        dismissed:
          type: boolean
        error:
          type: string
        healthy:
          type: boolean
          description: Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead.
        netcheck:
          $ref: '#/components/schemas/netcheck.Report'
        netcheck_err:
          type: string
        netcheck_logs:
          type: array
          items:
            type: string
        regions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/healthsdk.DERPRegionReport'
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    healthsdk.HealthSection:
      type: string
      enum:
      - DERP
      - AccessURL
      - Websocket
      - Database
      - WorkspaceProxy
      - ProvisionerDaemons
    health.Message:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/health.Code'
        message:
          type: string
    codersdk.WorkspaceProxyStatus:
      type: object
      properties:
        checked_at:
          type: string
          format: date-time
        report:
          description: Report provides more information about the health of the workspace proxy.
          allOf:
          - $ref: '#/components/schemas/codersdk.ProxyHealthReport'
        status:
          $ref: '#/components/schemas/codersdk.ProxyHealthStatus'
    codersdk.Response:
      type: object
      properties:
        detail:
          type: string
          description: 'Detail is a debug message that provides further insight into why the

            action failed. This information can be technical and a regular golang

            err.Error() text.

            - "database: too many open connections"

            - "stat: too many open files"'
        message:
          type: string
          description: 'Message is an actionable message that depicts actions the request took.

            These messages should be fully formed sentences with proper punctuation.

            Examples:

            - "A user has been created."

            - "Failed to create a user."'
        validations:
          type: array
          description: 'Validations are form field-specific friendly error messages. They will be

            shown on a form field in the UI. These can also be used to add additional

            context if there is a set of errors in the primary ''Message''.'
          items:
            $ref: '#/components/schemas/codersdk.ValidationError'
    healthsdk.UpdateHealthSettings:
      type: object
      properties:
        dismissed_healthchecks:
          type: array
          items:
            $ref: '#/components/schemas/healthsdk.HealthSection'
    health.Code:
      type: string
      enum:
      - EUNKNOWN
      - EWP01
      - EWP02
      - EWP04
      - EDB01
      - EDB02
      - EWS01
      - EWS02
      - EWS03
      - EACS01
      - EACS02
      - EACS03
      - EACS04
      - EDERP01
      - EDERP02
      - EDERP03
      - EPD01
      - EPD02
      - EPD03
    derp.ServerInfoMessage:
      type: object
      properties:
        tokenBucketBytesBurst:
          type: integer
          description: 'TokenBucketBytesBurst is how many bytes the server will

            allow to burst, temporarily violating

            TokenBucketBytesPerSecond.


            Zero means unspecified. There might be a limit, but the

            client need not try to respect it.'
        tokenBucketBytesPerSecond:
          type: integer
          description: 'TokenBucketBytesPerSecond is how many bytes per second the

            server says it will accept, including all framing bytes.


            Zero means unspecified. There might be a limit, but the

            client need not try to respect it.'
    tailcfg.DERPRegion:
      type: object
      properties:
        avoid:
          type: boolean
          description: 'Avoid is whether the client should avoid picking this as its home

            region. The region should only be used if a peer is there.

            Clients already using this region as their home should migrate

            away to a new region without Avoid set.'
        embeddedRelay:
          type: boolean
          description: 'EmbeddedRelay is true when the region is bundled with the Coder

            control plane.'
        nodes:
          type: array
          description: 'Nodes are the DERP nodes running in this region, in

            priority order for the current client. Client TLS

            connections should ideally only go to the first entry

            (falling back to the second if necessary). STUN packets

            should go to the first 1 or 2.


            If nodes within a region route packets amongst themselves,

            but not to other regions. That said, each user/domain

            should get a the same preferred node order, so if all nodes

            for a user/network pick the first one (as they should, when

            things are healthy), the inter-cluster routing is minimal

            to zero.'
          items:
            $ref: '#/components/schemas/tailcfg.DERPNode'
        regionCode:
          type: string
          description: 'RegionCode is a short name for the region. It''s usually a popular

            city or airport code in the region: "nyc", "sf", "sin",

            "fra", etc.'
        regionID:
          type: integer
          description: 'RegionID is a unique integer for a geographic region.


            It corresponds to the legacy derpN.tailscale.com hostnames

            used by older clients. (Older clients will continue to resolve

            derpN.tailscale.com when contacting peers, rather than use

            the server-provided DERPMap)


            RegionIDs must be non-zero, positive, and guaranteed to fit

            in a JavaScript number.


            RegionIDs in range 900-999 are reserved for end users to run their

            own DERP nodes.'
        regionName:
          type: string
          description: 'RegionName is a long English name for the region: "New York City",

            "San Francisco", "Singapore", "Frankfurt", etc.'
    healthsdk.DERPNodeReport:
      type: object
      properties:
        can_exchange_messages:
          type: boolean
        client_errs:
          type: array
          items:
            type: array
            items:
              type: string
        client_logs:
          type: array
          items:
            type: array
            items:
              type: string
        error:
          type: string
        healthy:
          type: boolean
          description: Healthy is deprecated and left for backward compatibility purposes, use `Severity` instead.
        node:
          $ref: '#/components/schemas/tailcfg.DERPNode'
        node_info:
          $ref: '#/components/schemas/derp.ServerInfoMessage'
        round_trip_ping:
          type: string
        round_trip_ping_ms:
          type: integer
        severity:
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        stun:
          $ref: '#/components/schemas/healthsdk.STUNReport'
        uses_websocket:
          type: boolean
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/health.Message'
    codersdk.ValidationError:
      type: object
      properties:
        detail:
          type: string
        field:
          type: string
      required:
      - detail
      - field
    healthsdk.HealthSettings:
      type: object
      properties:
        dismissed_healthchecks:
          type: array
          items:
            $ref: '#/components/schemas/healthsdk.HealthSection'
    netcheck.Report:
      type: object
      properties:
        captivePortal:
          type: string
          description: 'CaptivePortal is set when we think there''s a captive portal that is

            intercepting HTTP traffic.'
        globalV4:
          type: string
          description: ip:port of global IPv4
        globalV6:
          type: string
          description: '[ip]:port of global IPv6'
        hairPinning:
          type: string
          description: 'HairPinning is whether the router supports communicating

            between two local devices through the NATted public IP address

            (on IPv4).'
        icmpv4:
          type: boolean
          description: an ICMPv4 round trip completed
        ipv4:
          type: boolean
          description: an IPv4 STUN round trip completed
        ipv4CanSend:
          type: boolean
          description: an IPv4 packet was able to be sent
        ipv6:
          type: boolean
          description: an IPv6 STUN round trip completed
        ipv6CanSend:
          type: boolean
          description: an IPv6 packet was able to be sent
        mappingVariesByDestIP:
          type: string
          description: 'MappingVariesByDestIP is whether STUN results depend which

            STUN server you''re talking to (on IPv4).'
        oshasIPv6:
          type: boolean
          description: could bind a socket to ::1
        pcp:
          type: string
          description: 'PCP is whether PCP appears present on the LAN.

            Empty means not checked.'
        pmp:
          type: string
          description: 'PMP is whether NAT-PMP appears present on the LAN.

            Empty means not checked.'
        preferredDERP:
          type: integer
          description: or 0 for unknown
        regionLatency:
          type: object
          description: keyed by DERP Region ID
          additionalProperties:
            type: integer
            format: int64
        regionV4Latency:
          type: object
          description: keyed by DERP Region ID
          additionalProperties:
            type: integer
            format: int64
        regionV6Latency:
          type: object
          description: keyed by DERP Region ID
          additionalProperties:
            type: integer
            format: int64
        udp:
          type: boolean
          description: a UDP STUN round trip completed
        upnP:
          type: string
          description: 'UPnP is whether UPnP appears present on the LAN.

            Empty means not checked.'
    health.Severity:
      type: string
      enum:
      - ok
      - warning
      - error
    tailcfg.DERPNode:
      type: object
      properties:
        canPort80:
          type: boolean
          description: 'CanPort80 specifies whether this DERP node is accessible over HTTP

            on port 80 specifically. This is used for captive portal checks.'
        certName:
          type: string
          description: 'CertName optionally specifies the expected TLS cert common

            name. If empty, HostName is used. If CertName is non-empty,

            HostName is only used for the TCP dial (if IPv4/IPv6 are

            not present) + TLS ClientHello.'
        derpport:
          type: integer
          description: 'DERPPort optionally provides an alternate TLS port number

            for the DERP HTTPS server.


            If zero, 443 is used.'
        forceHTTP:
          type: boolean
          description: 'ForceHTTP is used by unit tests to force HTTP.

            It should not be set by users.'
        hostName:
          type: string
          description: 'HostName is the DERP node''s hostname.


            It is required but need not be unique; multiple nodes may

            have the same HostName but vary in configuration otherwise.'
        insecureForTests:
          type: boolean
          description: 'InsecureForTests is used by unit tests to disable TLS verification.

            It should not be set by users.'
        ipv4:
          type: string
          description: 'IPv4 optionally forces an IPv4 address to use, instead of using DNS.

            If empty, A record(s) from DNS lookups of HostName are used.

            If the string is not an IPv4 address, IPv4 is not used; the

            conventional string to disable IPv4 (and not use DNS) is

            "none".'
        ipv6:
          type: string
          description: 'IPv6 optionally forces an IPv6 address to use, instead of using DNS.

            If empty, AAAA record(s) from DNS lookups of HostName are used.

            If the string is not an IPv6 address, IPv6 is not used; the

            conventional string to disable IPv6 (and not use DNS) is

            "none".'
        name:
          type: string
          description: 'Name is a unique node name (across all regions).

            It is not a host name.

            It''s typically of the form "1b", "2a", "3b", etc. (region

            ID + suffix within that region)'
        regionID:
          type: integer
          description: 'RegionID is the RegionID of the DERPRegion that this node

            is running in.'
        stunonly:
          type: boolean
          description: 'STUNOnly marks a node as only a STUN server and not a DERP

            server.'
        stunport:
          type: integer
          description: 'Port optionally specifies a STUN port to use.

            Zero means 3478.

            To disable STUN on this node, use -1.'
        stuntestIP:
          type: string
          description: 'STUNTestIP is used in tests to override the STUN server''s IP.

            If empty, it''s assumed to be the same as the DERP server.'
    healthsdk.HealthcheckReport:
      type: object
      properties:
        access_url:
          $ref: '#/components/schemas/healthsdk.AccessURLReport'
        coder_version:
          type: string
          description: The Coder version of the server that the report was generated on.
        database:
          $ref: '#/components/schemas/healthsdk.DatabaseReport'
        derp:
          $ref: '#/components/schemas/healthsdk.DERPHealthReport'
        healthy:
          type: boolean
          description: 'Healthy is true if the report returns no errors.

            Deprecated: use `Severity` instead'
        provisioner_daemons:
          $ref: '#/components/schemas/healthsdk.ProvisionerDaemonsReport'
        severity:
          description: Severity indicates the status of Coder health.
          enum:
          - ok
          - warning
          - error
          allOf:
          - $ref: '#/components/schemas/health.Severity'
        time:
          type: string
          format: date-time
          description: Time is the time the report was generated at.
        websocket:
          $ref: '#/components/schemas/healthsdk.WebsocketReport'
        workspace_proxy:
          $ref: '#/components/schemas/healthsdk.WorkspaceProxyReport'
  securitySchemes:
    CoderSessionToken:
      type: apiKey
      in: header
      name: Coder-Session-Token
externalDocs: {}