logo

AiGenerate

Get the details of all data generate operations

SecurityApiKeyAuth
Request
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of objects to return per query. The value must be between 1 and 1000. Default is 100.

Example: limit=50
cursor
string [ 1 .. 4096 ] characters

Cursor to fetch the next or previous page of results. The value of this property must be extracted from the 'prev_cursor' or 'next_cursor' property of a PaginatedResponseMetadata which is contained in the response of list and search API endpoints.

sort
string or null

The field to sort results by. A property name with a prepended '-' signifies a descending order.

Enum: "id" "-id" "name" "-name" "description" "-description" "status" "-status" "data_type" "-data_type" "requested_count" "-requested_count" "generated_count" "-generated_count" "allow_duplicates" "-allow_duplicates" "max_value_length" "-max_value_length" "trim_values" "-trim_values" "filter_characters" "-filter_characters" "multiline_values" "-multiline_values" "expiration_time" "-expiration_time" "account_id" "-account_id" "priority" "-priority" "submit_time" "-submit_time" "start_time" "-start_time" "end_time" "-end_time" "llm_model_name" "-llm_model_name" "error_tolerance" "-error_tolerance"
Example: sort=name
Responses
200

Success

default

Unexpected Error

get/ai/generate
Response samples
application/json
{
  • "items": [
    ],
  • "response_metadata": {
    }
}

Initiate an operation that creates a list of data values using generative AI

SecurityApiKeyAuth
Request
Request Body schema: application/json
name
required
string

A name for this data generation request. This name will be used for the generated file, if requested.

description
string

An optional description for this data generation request

data_type
required
string

The type of data to generate

Array of objects (GenerateDataAttribute) >= 0 items

Attributes to use when generating some values. For each attribute, generation will iterate over each value, so each attribute value will apply to a subset of the generated values. An empty "" in the values list will cause generation skip this attribute for some generated values.

max_value_length
integer <int32> [ 1 .. 4000 ]

The maximum length in characters for each generated value. Generated values which are too long are discarded. The default value depends on whether multiline_values is enabled.

requested_count
integer <int32> >= 1
Default: 10

The number of values to generate

filter_characters
string
Default: ""

A Java regular expression that matches each character to filter from the generated values.

allow_duplicates
boolean
Default: false

Whether to allow duplicate values in the generated value list

trim_values
boolean
Default: true

Whether to trim leading and trailing whitespace from generated values.

multiline_values
required
boolean

Whether to allow generation of multiline values. Values generated with this setting true cannot be exported to secure lookup files. When this value is false, multiline values are rejected.

retention_time
integer <int64>

The length of time, in seconds, that generated values should be made available in the API. Values will always be available while the generated request is running. No value means data will be retained indefinitely.

error_tolerance
integer <int32>
Default: 300

The quantity of unusable, duplicate or failed LLM prompts allowed before the generate operation will fail. This value is expressed as a percentage multiple of total expected number of prompts need to complete the generate operation. Given the high likelihood of duplicate values, this value should not be decreased unless it is critical to time/resource bound the generate operation.

priority
integer <int32>
Default: 0

The request priority, where higher values mean higher priority. This will typically be 0 for bulk operations and 1 for sample generation.

Responses
200

Success

default

Unexpected Error

post/ai/generate
Request samples
application/json
{
  • "name": "German first names",
  • "description": "A list of 65 German first names",
  • "data_type": "first name",
  • "attributes": [
    ],
  • "max_value_length": 20,
  • "requested_count": 65,
  • "filter_characters": "[{}]",
  • "allow_duplicates": false,
  • "trim_values": true,
  • "multiline_values": true,
  • "retention_time": 3600,
  • "error_tolerance": 500,
  • "priority": 0
}
Response samples
application/json
{
  • "job": {
    }
}

Search for the details of data generate operations

SecurityApiKeyAuth
Request
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of objects to return per query. The value must be between 1 and 1000. Default is 100.

Example: limit=50
cursor
string [ 1 .. 4096 ] characters

Cursor to fetch the next or previous page of results. The value of this property must be extracted from the 'prev_cursor' or 'next_cursor' property of a PaginatedResponseMetadata which is contained in the response of list and search API endpoints.

sort
string or null

The field to sort results by. A property name with a prepended '-' signifies a descending order.

Enum: "id" "-id" "name" "-name" "description" "-description" "status" "-status" "data_type" "-data_type" "requested_count" "-requested_count" "generated_count" "-generated_count" "allow_duplicates" "-allow_duplicates" "max_value_length" "-max_value_length" "trim_values" "-trim_values" "filter_characters" "-filter_characters" "multiline_values" "-multiline_values" "expiration_time" "-expiration_time" "account_id" "-account_id" "priority" "-priority" "submit_time" "-submit_time" "start_time" "-start_time" "end_time" "-end_time" "llm_model_name" "-llm_model_name" "error_tolerance" "-error_tolerance"
Example: sort=name
Request Body schema: application/json

A request body containing a filter expression. This enables searching for items matching arbitrarily complex conditions. The list of attributes which can be used in filter expressions is available in the x-filterable vendor extension.

Filter Expression Overview

Note: All keywords are case-insensitive

Comparison Operators

Operator Description Example
CONTAINS Substring or membership testing for string and list attributes respectively. field3 CONTAINS 'foobar', field4 CONTAINS TRUE
IN Tests if field is a member of a list literal. List can contain a maximum of 100 values field2 IN ['Goku', 'Vegeta']
GE Tests if a field is greater than or equal to a literal value field1 GE 1.2e-2
GT Tests if a field is greater than a literal value field1 GT 1.2e-2
LE Tests if a field is less than or equal to a literal value field1 LE 9000
LT Tests if a field is less than a literal value field1 LT 9.02
NE Tests if a field is not equal to a literal value field1 NE 42
EQ Tests if a field is equal to a literal value field1 EQ 42

Search Operator

The SEARCH operator filters for items which have any filterable attribute that contains the input string as a substring, comparison is done case-insensitively. This is not restricted to attributes with string values. Specifically SEARCH '12' would match an item with an attribute with an integer value of 123.

Logical Operators

Ordered by precedence.

Operator Description Example
NOT Logical NOT (Right associative) NOT field1 LE 9000
AND Logical AND (Left Associative) field1 GT 9000 AND field2 EQ 'Goku'
OR Logical OR (Left Associative) field1 GT 9000 OR field2 EQ 'Goku'

Grouping

Parenthesis () can be used to override operator precedence.

For example: NOT (field1 LT 1234 AND field2 CONTAINS 'foo')

Literal Values

Literal Description Examples
Nil Represents the absence of a value nil, Nil, nIl, NIL
Boolean true/false boolean true, false, True, False, TRUE, FALSE
Number Signed integer and floating point numbers. Also supports scientific notation. 0, 1, -1, 1.2, 0.35, 1.2e-2, -1.2e+2
String Single or double quoted "foo", "bar", "foo bar", 'foo', 'bar', 'foo bar'
Datetime Formatted according to RFC3339 2018-04-27T18:39:26.397237+00:00
List Comma-separated literals wrapped in square brackets [0], [0, 1], ['foo', "bar"]

Limitations

  • A maximum of 8 unique identifiers may be used inside a filter expression.
filter_expression
string [ 5 .. 50000 ] characters
Responses
200

Success

default

Unexpected Error

post/ai/generate/search
Request samples
application/json

An example of a nested Object comparison testing that at least one repository has a version which is equal to 19.0.0.

{
  • "filter_expression": "repositories CONTAINS {version eq '19.0.0'}"
}
Response samples
application/json
{
  • "items": [
    ],
  • "response_metadata": {
    }
}

Get the details of a data generate operation

SecurityApiKeyAuth
Request
path Parameters
generateDataOperationId
required
string non-empty

The id of the generate data operation

Responses
200

Success

default

Unexpected Error

get/ai/generate/{generateDataOperationId}
Response samples
application/json
{
  • "id": "a638d976-6b7e-43f4-9212-90f4dc6d405c",
  • "name": "German first names",
  • "description": "A list of 200 German first names",
  • "status": "STARTED",
  • "data_type": "first name",
  • "attributes": [
    ],
  • "max_value_length": 20,
  • "requested_count": 65,
  • "generated_count": 65,
  • "filter_characters": "string",
  • "allow_duplicates": true,
  • "trim_values": true,
  • "multiline_values": true,
  • "account_id": "1",
  • "submit_time": "2022-11-15T08:51:34.000Z",
  • "start_time": "2022-11-15T08:52:12.000Z",
  • "end_time": "2022-11-15T09:07:00.000Z",
  • "expiration_time": "2022-11-16T09:07:00.000Z",
  • "error_tolerance": 300,
  • "ai_orchestrator_id": "string",
  • "llm_model_name": "llama3.2:1b",
  • "priority": 0
}

Get all values generated by a data generate operation

SecurityApiKeyAuth
Request
path Parameters
generateDataOperationId
required
string non-empty

The id of the generate data operation

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of objects to return per query. The value must be between 1 and 1000. Default is 100.

Example: limit=50
cursor
string [ 1 .. 4096 ] characters

Cursor to fetch the next or previous page of results. The value of this property must be extracted from the 'prev_cursor' or 'next_cursor' property of a PaginatedResponseMetadata which is contained in the response of list and search API endpoints.

sort
string or null

The field to sort results by. A property name with a prepended '-' signifies a descending order.

Enum: "value" "-value"
Example: sort=value
Responses
200

Success

default

Unexpected Error

get/ai/generate/{generateDataOperationId}/values
Response samples
application/json
{
  • "items": [
    ],
  • "response_metadata": {
    }
}

Download all values generated by the operation in the specified format

SecurityApiKeyAuth
Request
path Parameters
generateDataOperationId
required
string non-empty

The id of the generate data operation

query Parameters
format
required
string

The format for the generated file

Enum: "JSON" "SECURE_LOOKUP"
Responses
200

OK

default

Unexpected Error

get/ai/generate/{generateDataOperationId}/download
Response samples
application/json
{
  • "error": "string",
  • "error_description": "string"
}
➔ Next to Jobs