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: /api/v2 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