invocable-scripts.yml

openapi: 3.0.0
info:
  title: InfluxData Invokable Scripts API
  version: 0.1.0
  description: |
    Manage and execute scripts as API endpoints in InfluxDB.

    An API Invokable Script assigns your custom Flux script to a new InfluxDB API endpoint for your organization.
    Invokable scripts let you execute your script as an HTTP request to the endpoint.

    Invokable scripts accept parameters. Add parameter references in your script as `params.myparameter`.
    When you `invoke` your script, you send parameters as key-value pairs in the `params` object.
    InfluxDB executes your script with the key-value pairs as arguments and returns the result.

    For more information and examples, see [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/).
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
servers:
  - url: /
paths:
  /scripts:
    get:
      operationId: GetScripts
      tags:
        - Data I/O endpoints
        - Invokable Scripts
      summary: List scripts
      description: |
        Lists [scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/).

        #### Related guides

        - [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/)
      parameters:
        - in: query
          name: offset
          required: false
          description: |
            The offset for pagination.
            The number of records to skip.

            For more information about pagination parameters, see [Pagination]({{% INFLUXDB_DOCS_URL %}}/api/#tag/Pagination).
          schema:
            type: integer
            minimum: 0
        - in: query
          name: limit
          description: |
            The maximum number of scripts to return. Default is `100`.
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 500
            default: 100
        - in: query
          name: name
          required: false
          description: The script name. Lists scripts with the specified name.
          schema:
            type: string
      responses:
        '200':
          description: |
            Success.
            The response body contains the list of scripts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Scripts'
              examples:
                successResponse:
                  value:
                    scripts:
                      - id: 09afa3b220fe4000
                        orgID: bea7ea952287f70d
                        name: getLastPointFromSampleBucket
                        script: 'from(bucket: SampleBucket) |> range(start: -7d) |> limit(n:1)'
                        description: find the last point from Sample Bucket
                        language: flux
                        createdAt: '2022-07-17T23:49:45.731237Z'
                        updatedAt: '2022-07-17T23:49:45.731237Z'
                      - id: 09afa23ff13e4000
                        orgID: bea7ea952287f70d
                        name: getLastPoint
                        script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)'
                        description: getLastPoint finds the last point in a bucket
                        language: flux
                        createdAt: '2022-07-17T23:43:26.660308Z'
                        updatedAt: '2022-07-17T23:43:26.660308Z'
        '400':
          description: |
            Bad request.
            InfluxDB is unable to parse the request.
            The response body contains detail about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidSyntaxError:
                  summary: Query parameter contains invalid syntax.
                  value:
                    code: 3
                    message: 'parsing field "limit": strconv.ParseUint: parsing "-1": invalid syntax'
                    details: []
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Shell
          label: 'cURL: retrieves the first 100 scripts.'
          source: |
            curl --request GET "INFLUX_URL/api/v2/scripts?limit=100&offset=0" \
              --header "Authorization: Token INFLUX_API_TOKEN" \
              --header "Accept: application/json" \
              --header "Content-Type: application/json"
    post:
      operationId: PostScripts
      tags:
        - Invokable Scripts
      summary: Create a script
      description: |
        Creates an [invokable script](https://docs.influxdata.com/resources/videos/api-invokable-scripts/)
        and returns the script.

        #### Related guides

        - [Invokable scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/)
        - [Creating custom InfluxDB endpoints](https://docs.influxdata.com/resources/videos/api-invokable-scripts/)
      requestBody:
        description: The script to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScriptCreateRequest'
      responses:
        '201':
          description: |
            Success.
            The response body contains the script and its metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
              examples:
                successResponse:
                  value:
                    id: 09afa23ff13e4000
                    orgID: bea7ea952287f70d
                    name: getLastPoint
                    script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)'
                    description: getLastPoint finds the last point in a bucket
                    language: flux
                    createdAt: '2022-07-17T23:43:26.660308Z'
                    updatedAt: '2022-07-17T23:43:26.660308Z'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '422':
          description: |
            Unprocessable entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                uniquenessError:
                  description: |
                    A script with the same `name` exists.
                  value:
                    code: conflict
                    message: uniqueness violation
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |
            curl --request POST "INFLUX_URL/api/v2/scripts" \
              --header "Authorization: Token INFLUX_API_TOKEN" \
              --header "Accept: application/json" \
              --header "Content-Type: application/json" \
              --data '{
                  "name": "getLastPoint",
                  "description": "getLastPoint finds the last point in a bucket",
                  "orgID": "INFLUX_ORG_ID",
                  "script": "from(bucket: INFLUX_BUCKET) |> range(start: -7d) |> limit(n:1)",
                  "language": "flux"
                }'
  '/scripts/{scriptID}':
    get:
      operationId: GetScriptsID
      tags:
        - Data I/O endpoints
        - Invokable Scripts
      summary: Retrieve a script
      description: |
        Retrieves a [script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/).

        #### Related Guides

        - [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/)
      parameters:
        - in: path
          name: scriptID
          schema:
            type: string
          required: true
          description: |
            A script ID.
            Retrieves the specified script.
      responses:
        '200':
          description: Success. The response body contains the script.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
              examples:
                successResponse:
                  value:
                    id: 09afa3b220fe4000
                    orgID: bea7ea952287f70d
                    name: getLastPoint
                    script: 'from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)'
                    description: getLastPoint finds the last point in a bucket
                    language: flux
                    createdAt: '2022-07-17T23:49:45.731237Z'
                    updatedAt: '2022-07-17T23:49:45.731237Z'
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          description: |
            Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                notFound:
                  summary: |
                    The requested script was not found.
                  value:
                    code: not found
                    message: script "09afa3b220fe400" not found
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Internal server error.
          $ref: '#/components/responses/ServerError'
    patch:
      operationId: PatchScriptsID
      tags:
        - Invokable Scripts
      summary: Update a script
      description: |
        Updates an invokable script.

        Use this endpoint to modify values for script properties (`description` and `script`).

        To update a script, pass an object that contains the updated key-value pairs.

        #### Limitations

        - If you send an empty request body, the script will neither update nor
        store an empty script, but InfluxDB will respond with an HTTP `200` status
        code.

        #### Related Guides

        - [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/)
      requestBody:
        description: |
          An object that contains the updated script properties to apply.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScriptUpdateRequest'
      parameters:
        - in: path
          name: scriptID
          schema:
            type: string
          required: true
          description: |
            A script ID.
            Updates the specified script.
      responses:
        '200':
          description: Success. The response body contains the updated script.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Script'
              examples:
                successResponse:
                  value:
                    id: 09afa3b220fe4000
                    orgID: bea7ea952287f70d
                    name: getLastPoint
                    script: 'from(bucket: newBucket) |> range(start: -7d) |> limit(n:1)'
                    description: get last point from new bucket
                    language: flux
                    createdAt: '2022-07-17T23:49:45.731237Z'
                    updatedAt: '2022-07-19T22:27:23.185436Z'
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          description: |
            Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                notFound:
                  summary: |
                    The requested script wasn't found.
                  value:
                    code: not found
                    message: script "09afa3b220fe400" not found
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Internal server error
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |
            curl -X 'PATCH' \
              "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \
              --header "Authorization: Token INFLUX_TOKEN" \
              --header "Accept: application/json"
              --header "Content-Type: application/json"
              --data '{
                  "description": "get last point from new bucket",
                  "script": "from(bucket: updatedBucket) |> range(start: -7d) |> limit(n:1)", "language": "flux"
                }'
    delete:
      operationId: DeleteScriptsID
      tags:
        - Invokable Scripts
      summary: Delete a script
      description: |
        Deletes a [script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/) and all associated records.

        #### Limitations

        - You can delete only one script per request.
        - If the script ID you provide doesn't exist for the organization, InfluxDB
        responds with an HTTP `204` status code.

        #### Related Guides

        - [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/)
      parameters:
        - in: path
          name: scriptID
          schema:
            type: string
          required: true
          description: |
            A script ID.
            Deletes the specified script.
      responses:
        '204':
          description: |
            Success.
            The script is queued for deletion.
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected error
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |
            curl -X 'DELETE' \
              "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \
              --header "Authorization: Token INFLUX_TOKEN" \
              --header 'Accept: application/json'
  '/scripts/{scriptID}/invoke':
    post:
      operationId: PostScriptsIDInvoke
      tags:
        - Data I/O endpoints
        - Invokable Scripts
      summary: Invoke a script
      description: |
        Runs a script and returns the result.
        When the script runs, InfluxDB replaces `params` keys referenced in the script with
        `params` key-values passed in the request body--for example:

        The following sample script contains a _`mybucket`_ parameter :

        ```json
        "script": "from(bucket: params.mybucket)
                    |> range(start: -7d)
                    |> limit(n:1)"
        ```

        The following example `POST /api/v2/scripts/SCRIPT_ID/invoke` request body
        passes a value for the _`mybucket`_ parameter:

        ```json
        {
          "params": {
            "mybucket": "air_sensor"
          }
        }
        ```

        #### Related guides

        - [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/)
      parameters:
        - in: path
          name: scriptID
          description: |
            A script ID.
            Runs the specified script.
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScriptInvocationParams'
      responses:
        '200':
          description: |
            Success.
            The response body contains the result of the script execution.
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/ScriptHTTPResponseData'
              examples:
                successResponse:
                  value: |
                    ,result,table,_start,_stop,_time,_value,_field,_measurement,host
                    ,_result,0,2019-10-30T01:28:02.52716421Z,2022-07-26T01:28:02.52716421Z,2020-01-01T00:00:00Z,72.01,used_percent,mem,host2
        '400':
          description: |
            Bad request.
            InfluxDB is unable to parse the request.
            The response body contains detail about the error.
          headers:
            X-Platform-Error-Code:
              description: |
                The reason for the error.
              schema:
                type: string
                example: invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidParameters:
                  summary: The parameters passed to the script are invalid.
                  value:
                    code: invalid
                    message: invalid parameters provided
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          description: |
            Not found.
          headers:
            X-Platform-Error-Code:
              description: |
                The reason for the error.
              schema:
                type: string
                example: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                scriptNotFound:
                  summary: |
                    Script not found
                  description: InfluxDB can't find the requested script.
                  value:
                    code: not found
                    message: script "09afa3b220fe400" not found
                bucketNotFound:
                  summary: |
                    Bucket not found
                  description: InfluxDB can't find the requested bucket.
                  value:
                    code: not found
                    message: 'failed to initialize execute state: could not find bucket "test-bucket"'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |
            curl --request POST "INFLUX_URL/api/v2/scripts/SCRIPT_ID/invoke" \
                      --header "Authorization: Token INFLUX_TOKEN" \
                      --header 'Accept: application/csv' \
                      --header 'Content-Type: application/json' \
                      --data '{
                        "params": {
                            "mybucket": "air_sensor"
                            }
                        }'
  '/scripts/{scriptID}/params':
    get:
      operationId: GetScriptsIDParams
      tags:
        - Invokable Scripts
      summary: Find script parameters.
      description: |
        Analyzes a script and determines required parameters.
        Find all `params` keys referenced in a script and return a list
        of keys. If it is possible to determine the type of the value
        from the context then the type is also returned -- for example:

        The following sample script contains a _`mybucket`_ parameter :

        ```json
        "script": "from(bucket: params.mybucket)
                    |> range(start: -7d)
                    |> limit(n:1)"
        ```

        Requesting the parameters using `GET /api/v2/scripts/SCRIPT_ID/params`
        returns the following:

        ```json
        {
          "params": {
            "mybucket": "string"
          }
        }
        ```

        The type name returned for a parameter will be one of:

         - `any`
         - `bool`
         - `duration`
         - `float`
         - `int`
         - `string`
         - `time`
         - `uint`

        The type name `any` is used when the type of a parameter cannot
        be determined from the context, or the type is determined to
        be a structured type such as an array or record.

        #### Related guides

        - [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/)
      parameters:
        - in: path
          name: scriptID
          description: |
            A script ID.
            The script to analyze for params.
          schema:
            type: string
          required: true
      responses:
        '200':
          description: |
            Success.
            The response body contains the parameters found, along with their types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Params'
              examples:
                successResponse:
                  value:
                    params:
                      mybucket: string
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          description: |
            Not found.
          headers:
            X-Platform-Error-Code:
              description: |
                The reason for the error.
              schema:
                type: string
                example: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                scriptNotFound:
                  summary: |
                    Script not found
                  description: InfluxDB can't find the requested script.
                  value:
                    code: not found
                    message: script "09afa3b220fe400" not found
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |
            curl --request GET "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/params" \
                      --header "Authorization: Token INFLUX_TOKEN"
components:
  responses:
    ServerError:
      description: Non 2XX error response from server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AuthorizationError:
      description: |
        Unauthorized. The error may indicate one of the following:

          * The `Authorization: Token` header is missing or malformed.
          * The API token value is missing from the header.
          * The token doesn't have sufficient permissions to write to this organization and bucket.
      content:
        application/json:
          schema:
            properties:
              code:
                description: |
                  The HTTP status code description. Default is `unauthorized`.
                readOnly: true
                type: string
                enum:
                  - unauthorized
              message:
                readOnly: true
                description: A human-readable message that may contain detail about the error.
                type: string
          examples:
            tokenNotAuthorized:
              summary: Token is not authorized to access a resource
              value:
                code: unauthorized
                message: unauthorized access
    BadRequestError:
      description: |
        Bad request.
        The response body contains detail about the error.

        #### InfluxDB OSS

        - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            orgProvidedNotFound:
              summary: The org or orgID passed doesn't own the token passed in the header
              value:
                code: invalid
                message: 'failed to decode request body: organization not found'
    InternalServerError:
      description: |
        Internal server error.
        The server encountered an unexpected situation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      properties:
        code:
          description: code is the machine-readable error code.
          readOnly: true
          type: string
          enum:
            - internal error
            - not implemented
            - not found
            - conflict
            - invalid
            - unprocessable entity
            - empty value
            - unavailable
            - forbidden
            - too many requests
            - unauthorized
            - method not allowed
            - request too large
            - unsupported media type
        message:
          readOnly: true
          description: Human-readable message.
          type: string
        op:
          readOnly: true
          description: Describes the logical code operation when the error occurred. Useful for debugging.
          type: string
        err:
          readOnly: true
          description: Stack of errors that occurred during processing of the request. Useful for debugging.
          type: string
      required:
        - code
    Params:
      type: object
      properties:
        params:
          type: object
          additionalProperties:
            type: string
            enum:
              - any
              - bool
              - duration
              - float
              - int
              - string
              - time
              - uint
          description: |
            The `params` keys and value type defined in the script.
    Script:
      properties:
        id:
          readOnly: true
          type: string
        name:
          type: string
        description:
          type: string
        orgID:
          type: string
        script:
          description: The script to execute.
          type: string
        language:
          $ref: '#/components/schemas/ScriptLanguage'
        url:
          type: string
          description: The invocation endpoint address.
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
      required:
        - name
        - orgID
        - script
    Scripts:
      type: object
      properties:
        scripts:
          type: array
          items:
            $ref: '#/components/schemas/Script'
    ScriptCreateRequest:
      type: object
      properties:
        name:
          description: Script name. The name must be unique within the organization.
          type: string
        description:
          description: Script description. A description of the script.
          type: string
        script:
          description: The script to execute.
          type: string
        language:
          $ref: '#/components/schemas/ScriptLanguage'
      required:
        - name
        - script
        - language
        - description
    ScriptUpdateRequest:
      type: object
      properties:
        description:
          description: A description of the script.
          type: string
        script:
          description: The script to execute.
          type: string
    ScriptHTTPResponseData:
      description: |
        The response body contains the results of the executed script.
        The response is user-defined and dynamic.
      type: string
      format: binary
    ScriptInvocationParams:
      type: object
      properties:
        params:
          type: object
          additionalProperties: true
          description: |
            The script parameters.
            `params` contains key-value pairs that map values to the **params.keys**
            in a script.
            When you invoke a script with `params`, InfluxDB passes the values as
            invocation parameters to the script.
    ScriptLanguage:
      type: string
      enum:
        - flux
        - sql
        - influxql