openapi: 3.0.0
info:
  title: Subset of Influx API covered by Influx CLI
  version: 2.0.0
servers:
  - url: /api/v2
paths:
  /health:
    servers:
      - url: ''
    get:
      operationId: GetHealth
      tags:
        - Health
      summary: Get the health of an instance
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
      responses:
        '200':
          description: The instance is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheck'
        '503':
          description: The instance is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheck'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /setup:
    get:
      operationId: GetSetup
      tags:
        - Setup
      summary: 'Check if database has default user, org, bucket'
      description: 'Returns `true` if no default user, organization, or bucket has been created.'
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
      responses:
        '200':
          description: allowed true or false
          content:
            application/json:
              schema:
                type: object
                properties:
                  allowed:
                    description: True means that the influxdb instance has NOT had initial setup; false means that the database has been setup.
                    type: boolean
    post:
      operationId: PostSetup
      tags:
        - Setup
      summary: 'Set up initial user, org and bucket'
      description: 'Post an onboarding request to set up initial user, org and bucket.'
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
      requestBody:
        description: Source to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingRequest'
      responses:
        '201':
          description: 'Created default user, bucket, org'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    TraceSpan:
      in: header
      name: Zap-Trace-Span
      description: OpenTracing span context
      example:
        trace_id: '1'
        span_id: '1'
        baggage:
          key: value
      required: false
      schema:
        type: string
  schemas:
    Error:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          readOnly: true
          description: message is a human-readable message.
          type: string
        op:
          readOnly: true
          description: op describes the logical code operation during error. Useful for debugging.
          type: string
        err:
          readOnly: true
          description: err is a stack of errors that occurred during processing of the request. Useful for debugging.
          type: string
      required:
        - code
        - message
    ErrorCode:
      description: code is the machine-readable error code.
      readOnly: true
      type: string
      enum:
        - internal error
        - not found
        - conflict
        - invalid
        - unprocessable entity
        - empty value
        - unavailable
        - forbidden
        - too many requests
        - unauthorized
        - method not allowed
        - request too large
    HealthCheck:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
        message:
          type: string
        checks:
          type: array
          items:
            $ref: '#/components/schemas/HealthCheck'
        status:
          $ref: '#/components/schemas/HealthCheckStatus'
        version:
          type: string
        commit:
          type: string
    HealthCheckStatus:
      type: string
      enum:
        - pass
        - fail
    OnboardingRequest:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
        org:
          type: string
        bucket:
          type: string
        retentionPeriodSeconds:
          type: integer
          format: int64
        retentionPeriodHrs:
          type: integer
          deprecated: true
          description: |
            Retention period *in nanoseconds* for the new bucket. This key's name has been misleading since OSS 2.0 GA, please transition to use `retentionPeriodSeconds`
        token:
          type: string
          description: |
            Authentication token to set on the initial user. If not specified, the server will generate a token.
      required:
        - username
        - org
        - bucket
    OnboardingResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserResponse'
        org:
          $ref: '#/components/schemas/Organization'
        bucket:
          $ref: '#/components/schemas/Bucket'
        auth:
          $ref: '#/components/schemas/Authorization'
    UserResponse:
      properties:
        id:
          readOnly: true
          type: string
        oauthID:
          type: string
        name:
          type: string
        status:
          description: If inactive the user is inactive.
          default: active
          type: string
          enum:
            - active
            - inactive
        links:
          type: object
          readOnly: true
          example:
            self: /api/v2/users/1
          properties:
            self:
              type: string
              format: uri
      required:
        - name
    Link:
      type: string
      format: uri
      readOnly: true
      description: URI of resource.
    Organization:
      properties:
        links:
          type: object
          readOnly: true
          example:
            self: /api/v2/orgs/1
            members: /api/v2/orgs/1/members
            owners: /api/v2/orgs/1/owners
            labels: /api/v2/orgs/1/labels
            secrets: /api/v2/orgs/1/secrets
            buckets: /api/v2/buckets?org=myorg
            tasks: /api/v2/tasks?org=myorg
            dashboards: /api/v2/dashboards?org=myorg
          properties:
            self:
              $ref: '#/components/schemas/Link'
            members:
              $ref: '#/components/schemas/Link'
            owners:
              $ref: '#/components/schemas/Link'
            labels:
              $ref: '#/components/schemas/Link'
            secrets:
              $ref: '#/components/schemas/Link'
            buckets:
              $ref: '#/components/schemas/Link'
            tasks:
              $ref: '#/components/schemas/Link'
            dashboards:
              $ref: '#/components/schemas/Link'
        id:
          readOnly: true
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        status:
          description: If inactive the organization is inactive.
          default: active
          type: string
          enum:
            - active
            - inactive
      required:
        - name
    Bucket:
      properties:
        links:
          type: object
          readOnly: true
          example:
            labels: /api/v2/buckets/1/labels
            members: /api/v2/buckets/1/members
            org: /api/v2/orgs/2
            owners: /api/v2/buckets/1/owners
            self: /api/v2/buckets/1
            write: /api/v2/write?org=2&bucket=1
          properties:
            labels:
              description: URL to retrieve labels for this bucket
              $ref: '#/components/schemas/Link'
            members:
              description: URL to retrieve members that can read this bucket
              $ref: '#/components/schemas/Link'
            org:
              description: URL to retrieve parent organization for this bucket
              $ref: '#/components/schemas/Link'
            owners:
              description: URL to retrieve owners that can read and write to this bucket.
              $ref: '#/components/schemas/Link'
            self:
              description: URL for this bucket
              $ref: '#/components/schemas/Link'
            write:
              description: URL to write line protocol for this bucket
              $ref: '#/components/schemas/Link'
        id:
          readOnly: true
          type: string
        type:
          readOnly: true
          type: string
          default: user
          enum:
            - user
            - system
        name:
          type: string
        description:
          type: string
        orgID:
          type: string
        rp:
          type: string
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        retentionRules:
          $ref: '#/components/schemas/RetentionRules'
        labels:
          $ref: '#/components/schemas/Labels'
      required:
        - name
        - retentionRules
    RetentionRules:
      type: array
      description: Rules to expire or retain data.  No rules means data never expires.
      items:
        $ref: '#/components/schemas/RetentionRule'
    RetentionRule:
      type: object
      properties:
        type:
          type: string
          default: expire
          enum:
            - expire
        everySeconds:
          type: integer
          format: int64
          description: Duration in seconds for how long data will be kept in the database. 0 means infinite.
          example: 86400
          minimum: 0
        shardGroupDurationSeconds:
          type: integer
          format: int64
          description: Shard duration measured in seconds.
      required:
        - type
        - everySeconds
    Labels:
      type: array
      items:
        $ref: '#/components/schemas/Label'
    Label:
      type: object
      properties:
        id:
          readOnly: true
          type: string
        orgID:
          readOnly: true
          type: string
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
          description: Key/Value pairs associated with this label. Keys can be removed by sending an update with an empty value.
          example:
            color: ffb3b3
            description: this is a description
    Authorization:
      required:
        - orgID
        - permissions
      allOf:
        - $ref: '#/components/schemas/AuthorizationUpdateRequest'
        - type: object
          properties:
            createdAt:
              type: string
              format: date-time
              readOnly: true
            updatedAt:
              type: string
              format: date-time
              readOnly: true
            orgID:
              type: string
              description: ID of org that authorization is scoped to.
            permissions:
              type: array
              minItems: 1
              description: List of permissions for an auth.  An auth must have at least one Permission.
              items:
                $ref: '#/components/schemas/Permission'
            id:
              readOnly: true
              type: string
            token:
              readOnly: true
              type: string
              description: Passed via the Authorization Header and Token Authentication type.
            userID:
              readOnly: true
              type: string
              description: ID of user that created and owns the token.
            user:
              readOnly: true
              type: string
              description: Name of user that created and owns the token.
            org:
              readOnly: true
              type: string
              description: Name of the org token is scoped to.
            links:
              type: object
              readOnly: true
              example:
                self: /api/v2/authorizations/1
                user: /api/v2/users/12
              properties:
                self:
                  readOnly: true
                  $ref: '#/components/schemas/Link'
                user:
                  readOnly: true
                  $ref: '#/components/schemas/Link'
    AuthorizationUpdateRequest:
      properties:
        status:
          description: If inactive the token is inactive and requests using the token will be rejected.
          default: active
          type: string
          enum:
            - active
            - inactive
        description:
          type: string
          description: A description of the token.
    Permission:
      required:
        - action
        - resource
      properties:
        action:
          type: string
          enum:
            - read
            - write
        resource:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - authorizations
                - buckets
                - dashboards
                - orgs
                - sources
                - tasks
                - telegrafs
                - users
                - variables
                - scrapers
                - secrets
                - labels
                - views
                - documents
                - notificationRules
                - notificationEndpoints
                - checks
                - dbrp
            id:
              type: string
              nullable: true
              description: If ID is set that is a permission for a specific resource. if it is not set it is a permission for all resources of that resource type.
            name:
              type: string
              nullable: true
              description: Optional name of the resource if the resource has a name field.
            orgID:
              type: string
              nullable: true
              description: If orgID is set that is a permission for all resources owned my that org. if it is not set it is a permission for all resources of that resource type.
            org:
              type: string
              nullable: true
              description: Optional name of the organization of the organization with orgID.