API docs by Redocly

Imply Polaris API (1.0.0)

Download OpenAPI specification:Download

You can use the Imply Polaris API to programmatically manage your tables, files, and ingestion tasks. See API overview for information and examples on how to get started.

Polaris API resources

Polaris API resources are either global or regional.

Global resources

You can access a global resource irrespective of the cloud provider or region in which Polaris hosts your project.

Global resources are relative to the base URL https://ORGANIZATION_NAME.api.imply.io, where ORGANIZATION_NAME is the custom domain through which you access Polaris.

The Polaris API supports the following global resources:

Regional resources

A regional resource is only accessible in the cloud and region where Polaris hosts your project. You must specify the project's cloud provider and region to call a regional resource. For more information, see Cloud providers and regions.

Regional resources are relative to the base URL https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID.

Replace the following:

  • ORGANIZATION_NAME: Custom domain through which you access Polaris.
  • REGION: Cloud region of your Polaris project.
  • CLOUD_PROVIDER: Cloud provider for your Polaris project.
  • PROJECT_ID: Unique identifier for your Polaris project.

For example: https://example.us-east-1.aws.api.imply.io/v1/projects/12375ffx-f7x4-4f0x-a1a6-3b3424987ee0/files.

The Polaris API supports the following regional resources:

For projects created after September 29, 2023, the Collections, Embedding, Events, Files, and Query APIs require the project ID in the base URL. We strongly recommend updating your regional API calls for existing projects to include the project ID prior to September 2024. See the API migration guide for more information.

Deprecated resources

The following Polaris API resources are deprecated. Instead, use the suggested replacements.

Deprecated resource Replacement Deprecation date Removal date
Connections v2 Connections v1 September 2023 September 2024
Embedding v1 Embedding links v1 February 2024 September 2024
Jobs v2 Jobs v1 September 2023 September 2024
Project v1 Projects v1 September 2023 September 2024
Tables v2 Tables v1 September 2023 September 2024

For more information, see Migration guide for deprecated APIs.

Status and error codes

Imply uses conventional HTTP response codes to indicate success or failure of a Polaris API request. In general:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed due to the information supplied in the request—for example, a required parameter is missing.
  • Codes in the 5xx range indicate an error with the Imply servers.

Some of the most commonly received status codes are as follows:

Code Description
200 - OK Successful request.
400 - Bad request The request was unacceptable, often due to missing a required parameter. The response usually contains information about the problem and how to resolve it.
401 - Unauthorized Valid OAuth credentials not found. See Authenticate API requests for information on obtaining credentials for Polaris API requests.
403 - Forbidden The supplied user credentials don't have permissions to perform the request.
404 - Not found The requested resource doesn't exist.
409 - Conflict The request can't complete—for example, due to a conflict with the current state of the target resource.
429 - Too many requests Too many requests hit the API too quickly. For push streaming requests the response contains details on how many requests you can send in a defined period and how long to wait until retry.
500, 502, 504 - Server errors Something went wrong at the Imply end. These are rare. Contact Polaris Support.
503 - Service unavailable Polaris is temporarily unavailable, usually for scheduled maintenance.

For more information see the official HTTP status code definitions.

Connections v1

Manage connections to external sources of data.

List all connections

Returns all existing connections.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connections belong.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a connection

Creates a new connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connections belong.

Request Body schema: application/json
required

A connection to be created.

container
required
string

Name of the container in the specified storage account in Azure Blob Storage.

name
required
string (ConnectionNamePayload) [ 1 .. 64 ] characters

Name of the connection. A connection name can only contain ASCII letters, numbers, and the following characters: ., _, -. The maximum length of a connection name is 64.

required
object (ConnectionSecretsRequiredPayload)

Type of connection secrets. The following secrets types are supported:

  • access_key: Access key to authenticate Azure Blob Storage or AWS S3 connections.
  • aws_iam: AWS IAM role assumption. Supported for Kafka (MSK) connections.
  • basic: Basic access authentication. Select this type for SQL connections or when you use a Confluent Schema Registry API key and secret.
  • confluent: Deprecated. For Confluent connections only. Instead use sasl_plain.
  • sas_token: Shared access signature (SAS) token for Azure Blob Storage.
  • sasl_plain: Authentication mechanism of SASL/PLAIN. Supported for Kafka and Confluent Cloud connections.
  • sasl_scram: Authentication mechanism of SASL/SCRAM. Supported for Kafka connections.
storageAccount
required
string

Name of the storage account in Azure Blob Storage.

type
required
string (ConnectionTypePayload)

Connection type. For reference on the information required for each connection type, see Create a connection.

description
string (ConnectionDescriptionPayload)

Optional description for the connection.

prefix
string

Prefix to restrict the connection to specific blobs.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-connection",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Response samples

Content type
application/json
Example
{
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2019-08-24T14:15:22Z",
  • "name": "example-connection",
  • "submittedByUser": {
    },
  • "submittedOnTimestamp": "2019-08-24T14:15:22Z",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Get connection details

Returns information for a single connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string (ConnectionNamePayload) [ 1 .. 64 ] characters
Example: example-connection

The name of the connection to get.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Responses

Response samples

Content type
application/json
Example
{
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2019-08-24T14:15:22Z",
  • "name": "example-connection",
  • "submittedByUser": {
    },
  • "submittedOnTimestamp": "2019-08-24T14:15:22Z",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Update a connection

Updates details for a specific connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

The name of the connection to update.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Request Body schema: application/json
required

The updated connection spec.

type
required
string (ConnectionTypePayload)

Connection type. For reference on the information required for each connection type, see Create a connection.

container
string

Name of the container in the specified storage account in Azure Blob Storage.

description
string (ConnectionDescriptionPayload)

Optional description for the connection.

prefix
string

Prefix to restrict the connection to specific blobs.

object (ConnectionSecretsOptionalPayload)

Type of connection secrets. The following secrets types are supported:

  • access_key: Access key to authenticate Azure Blob Storage or AWS S3 connections.
  • aws_iam: For AWS IAM role assumption. Supported for MSK (Kafka) connections.
  • basic: Basic access authentication. Select this type for SQL connections or when you use a Confluent Schema Registry API key and secret.
  • confluent: Deprecated. For Confluent connections only. Instead use sasl_plain.
  • sas_token: Shared access signature (SAS) token for Azure Blob Storage.
  • sasl_plain: Authentication mechanism of SASL/PLAIN. Supported for Kafka and Confluent Cloud connections.
  • sasl_scram: Authentication mechanism of SASL/SCRAM. Supported for Kafka connections.
storageAccount
string

Name of the storage account in Azure Blob Storage.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Response samples

Content type
application/json
Example
{
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2019-08-24T14:15:22Z",
  • "name": "example-connection",
  • "submittedByUser": {
    },
  • "submittedOnTimestamp": "2019-08-24T14:15:22Z",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Delete a connection

Deletes an existing connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

The name the connection to delete.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Test a connection

Checks whether an existing connection is valid.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

The name of the connection to test.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get meta information from connection

Returns meta information related to connections.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the meta information related to connections belongs.

Responses

Response samples

Content type
application/json
{
  • "externalId": "123e4567-e89b-12d3-a456-426614174000",
  • "implyArn": "arn:aws:iam::123456789012:role/imply-cluster-1234567"
}

Events v1

Push data from an application source through a push_streaming connection.

Push events to a Polaris connection

Sends data from an application source to a Polaris connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
connectionName
required
string

The name of the connection to push data to. Note that for legacy tables created via the v1 API, the connection name is named after the table ID.

projectId
required
string

The project ID for the request.

Request Body schema:
string <byte> (EventRequest)

Data to push to the Polaris table.

See Supported data and file formats for the data formats that Polaris supports for streaming ingestion.

The event data must include a timestamp value. For more information on event payload requirements, see Push event data by API.

Responses

Request samples

Content type
"{\"__time\":\"2022-04-16T00:46:58.771Z\",\"channel\":\"#en.wikipedia\",\"user\":\"GELongstreet\",\"added\":36,\"deleted\":0}\n{\"__time\":\"2022-04-17T04:07:28.781Z\",\"channel\":\"#de.wikipedia\",\"user\":\"Kolega2357\",\"added\":13,\"deleted\":16}"

Files v1

Upload, list, and delete files.

List files

List files.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project containing the files.

query Parameters
paginationLimit
integer [ 1 .. 1000 ]
Default: 1000

A result limit for pagination.

paginationOffset
integer >= 0
Default: 0

A result offset for pagination.

searchString
string

Filter the results to only include files that have the provided string contained within one of their fields.

sortColumn
string (FileSortColumn)
Default: "uploaded_on_dt"
Enum: "compression_format" "data_format" "digest_algo" "digest_hash" "name" "size_bytes" "uploaded_by_user_name" "uploaded_on_dt"

The column to sort file results by.

sortOrder
string (SortOrder)
Default: "DESC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order to sort file results by.

Responses

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "links": {
    },
  • "space": {
    },
  • "totalCount": 0
}

Upload a file

Uploads a file to the Polaris staging area.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project containing the files.

query Parameters
compressionFormat
string (CompressionFormat)
Enum: "none" "bz2" "gz" "sz" "xz" "zstd"
Example: compressionFormat=gz

If specified, the compression used for the file. Otherwise, Polaris infers the compression from the filename or the Content-Type HTTP header in the multipart form request.

Supported compression formats:

dataFormat
string (DataFormat)
Enum: "avro_ocf" "avro_stream" "csv" "kafka" "kinesis" "nd-json" "orc" "parquet" "protobuf"
Example: dataFormat=nd-json

If specified, the format of the data. Otherwise, Polaris infers the data format from the filename or the Content-Type HTTP header in the multipart form request.

For more information on supported data formats, see Supported data and file formats.

Request Body schema: multipart/form-data

A multipart/form-data request containing a single part with the file to be uploaded. You should not set the Content-Type: multipart/form-data header explicitly. Allow your client to assign the header automatically because it will also properly set the associated boundary directive.

The total size of the request including the file, HTTP headers, etc. must be less than 10 GB. This limit refers to the size of the file transmitted by the browser or HTTP client. You may upload a file that's larger than 10 GB on disk if your browser or client compresses the file in transit to below 10 GB.

File names must be unique. You cannot upload two files with the same name to Polaris.

file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "compressionFormat": "gz",
  • "dataFormat": "nd-json",
  • "digest": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "weather/20210603/01/hourly.json",
  • "sizeBytes": 207394342360,
  • "uploadedBy": {
    },
  • "uploadedOnDatetime": "2021-09-07T05:02:24Z"
}

Get file details

Returns information for a single file.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

Name of the file (may contain slashes)

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the file belongs.

Responses

Response samples

Content type
application/json
{
  • "compressionFormat": "gz",
  • "dataFormat": "nd-json",
  • "digest": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "weather/20210603/01/hourly.json",
  • "sizeBytes": 207394342360,
  • "uploadedBy": {
    },
  • "uploadedOnDatetime": "2021-09-07T05:02:24Z"
}

Delete a file

Deletes a file.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

Name of the file (may contain slashes)

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the file belongs.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Lookups v1

Create and manage lookups for Imply Polaris. See Lookups for more details about lookups and how to manage lookups in the Polaris UI.

List all lookups

Returns all lookups in a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a lookup

Creates a lookup in a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Request Body schema: application/json
required

A lookup to be created.

name
required
string

Unique name of the lookup.

required
object (LookupSourcePayload)

The source of a lookup. The following lookup type is supported:

  • table: A lookup source that references a table. The table must be partitioned by ALL granularity and contain a single segment.

Responses

Request samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Get lookup details

Returns details for a specified lookup.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Update a lookup

Updates the details of a specified lookup.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Request Body schema: application/json
required

The updated lookup request.

required
object (LookupSourcePayload)

The source of a lookup. The following lookup type is supported:

  • table: A lookup source that references a table. The table must be partitioned by ALL granularity and contain a single segment.

Responses

Request samples

Content type
application/json
{
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Delete a lookup

Deletes a lookup in a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

List all aliases for a lookup

Returns all aliases for a specified lookup.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create or update aliases for a lookup

Create or update the aliases for a specified lookup. You must provide the details of all aliases you want to retain for the lookup, even if you don't want to update them. Polaris recreates the lookup's aliases with the details you specify in the request. Polaris creates a new alias if the supplied alias name doesn't exist.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Request Body schema: application/json
required

A lookup alias to be created or updated.

required
Array of objects (LookupAliasPayload)

Responses

Request samples

Content type
application/json
{
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Jobs v1

Manage jobs in Imply Polaris.

List all jobs

Returns all jobs.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the project where the tables belong.

query Parameters
connectionName
Array of strings (ConnectionNamePayload) [ items [ 1 .. 64 ] characters ]
Example: connectionName=example-connection

The connection to filter jobs by.

executionStatus
Array of strings (JobExecutionStatusV2)
Items Enum: "pending" "running" "completed" "idle" "canceled" "failed" "suspended" "unknown"

Filters results with a certain execution status. For example, to list running jobs only, use the address /v1/projects/{projectId}/jobs?executionStatus=running.

healthStatus
Array of strings (JobHealthStatusV2)
Items Enum: "ok" "warn" "error"

Filters results with a certain health status. For example, to list jobs with warnings or errors, use the address /v1/projects/{projectId}/jobs?healthStatus=warn&healthStatus=error.

paginationLimit
integer [ 1 .. 1000 ]
Default: 100

A result limit for pagination.

paginationOffset
integer >= 0
Default: 0

A result offset for pagination.

searchString
string

Filter results to those jobs where the given string is contained in one of the job's fields.

sortColumn
string (JobSortSearchColumn)
Default: "last_updated_date_time"
Enum: "created_by_user_name" "created_date_time" "execution_status" "last_updated_date_time" "source_name" "source_type" "source_connection_name" "source_table_name" "target_table_name" "type"

Sort results by one of the following fields:

  • created_by_user_name : User that created the job.
  • created_date_time : Date the job was created.
  • execution_status : Job's execution status.
  • last_updated_date_time : Date the job was last updated.
  • source_name : Job's source name, such as a connection name.
  • source_type : Job's source type, such as connection or table.
  • source_connection_name : Deprecated, use source_name instead.
  • source_table_name : Deprecated, use source_name instead.
  • target_table_name : Table that the job targets.
  • type : Job type.
sortOrder
string (SortOrder)
Default: "DESC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order to sort job results by.

targetTableId
string <uuid> (TableId)

Filters results for jobs associated with a particular target table id.

targetTableName
string (TableName) [ 1 .. 255 ] characters
Example: targetTableName=example-table

Filters results for jobs associated with a particular target table name.

type
Array of strings (JobTypeV2)
Items Enum: "batch" "delete_data" "drop_table" "restore_data" "streaming" "sql"
Example: type=batch

Filters results with a certain job type. For example, to select batch and streaming jobs, use the address /v1/projects/{projectId}/jobs?type=batch&type=streaming.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "moreResultsAvailable": true
}

Create a job

Creates a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the project where the tables belong.

Request Body schema: application/json
required

A job to be created.

required
object (JobSourceV2)

Source input of the job.

required
object (JobTargetV2)

Target output of the job.

type
required
string (JobTypeV2)
Default: "sql"

Type of job:

  • batch - A batch ingestion job.
  • delete_data - A job to delete data within a table.
  • drop_table - A job to delete a table and all of its data.
  • restore_data - A job to restore deleted data in a table.
  • streaming - A streaming ingestion job.
  • sql - A SQL-based ingestion job.

You can't drop a table that's used as a lookup source.

For information about ingestion jobs, see Create an ingestion job and Ingest using SQL.

clusteringColumns
Array of strings (ClusteringColumns)

Optional columns to use for clustering. If specified, will take precedence over clustering columns defined on a table. Polaris sorts columns within a partition based on their order in this array.

For jobs targeting aggregate tables, only dimensions (not measures) are supported for clustering.

For more information, see Clustering.

object

Context parameters used to specify various query configuration parameters. For more information, see SQL ingestion reference.

createTableIfNotExists
boolean
Default: false

Whether the job should create the table if it doesn't already exist. For more information, see Introduction to tables.

filterExpression
string

SQL expression to use for filtering the source data. For more information, see Filter data to ingest.

ingestionMode
string (IngestionModeV2)
Default: "append"
Enum: "append" "replace"

Mode of ingestion:

  • append - Append newly ingested data to the existing data. To ingest a certain time range of source data, apply a filter expression to filter by a given time interval.
  • replace - Overwrite existing data for specific time intervals or all data in the table. Specify specific time intervals in target.intervals, or set "replaceAll": true. To restrict the time interval of what data Polaris ingests, use filter expressions.
Array of objects (InputToTableSchemaMappingsV2)
Default: []

Relationship between the input fields and the output columns of a table's schema. Define the Polaris column name in columnName, and specify how the column is defined with respect to the input fields in expression. expression must be a valid SQL expression.

For batch ingestion jobs, you must include a mapping for each field. Polaris ignores unmapped input fields. Streaming ingestion jobs may apply schema auto-discovery for Polaris to discover input fields and map them directly to table dimensions. Always specify a mapping for __time and when you want to transform an input field.

For more information, see Map and transform data with input expressions and Schema auto-discovery on ingestion jobs.

maxParseExceptions
integer
Default: 2147483647

Configuration parameter that specifies the maximum number of parse exceptions that a task can tolerate before failing.

partitionedBy
string (PartitioningGranularity)
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "month" "quarter" "year" "all"

Optional time partitioning. If specified, takes precedence over the time partitioning defined on the target table. If unspecified, defaults to the time partitioning of the table.

When ingesting into a lookup table, you can only set all partitioning.

replaceAll
boolean
Default: false

Replace all data with this job. Don't set this to true when the job's ingestion mode is append or when target.intervals is specified.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "batch",
  • "source": {
    },
  • "target": {
    },
  • "context": { },
  • "clusteringColumns": [
    ],
  • "createTableIfNotExists": false,
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "partitionedBy": "day",
  • "replaceAll": false
}

Response samples

Content type
application/json
Example
{
  • "createdBy": {
    },
  • "createdTimestamp": "2021-06-06T00:00:00.000Z",
  • "desiredExecutionStatus": "running",
  • "executionStatus": "pending",
  • "health": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "lastModifiedBy": {
    },
  • "lastUpdatedTimestamp": "2021-06-06T00:00:00.000Z",
  • "spec": {
    },
  • "target": {
    },
  • "type": "batch",
  • "completedTimestamp": "2021-06-06T00:00:00.000Z",
  • "startedTimestamp": "2021-06-06T00:00:00.000Z",
  • "source": {
    },
  • "context": { },
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "query": "string"
}

Get job details

Returns information for a single job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
Example
{
  • "createdBy": {
    },
  • "createdTimestamp": "2021-06-06T00:00:00.000Z",
  • "desiredExecutionStatus": "running",
  • "executionStatus": "pending",
  • "health": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "lastModifiedBy": {
    },
  • "lastUpdatedTimestamp": "2021-06-06T00:00:00.000Z",
  • "spec": {
    },
  • "target": {
    },
  • "type": "batch",
  • "completedTimestamp": "2021-06-06T00:00:00.000Z",
  • "startedTimestamp": "2021-06-06T00:00:00.000Z",
  • "source": {
    },
  • "context": { },
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "query": "string"
}

Update a job

Updates the execution status of a job.

Although you can continue to use this PUT request to update a job's status, it's recommended to use the POST request to the job status endpoint.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Request Body schema: application/json
required

The job to be updated.

desiredExecutionStatus
required
string (DesiredJobExecutionStatusV2)
Default: "running"
Enum: "running" "canceled" "suspended"

Desired execution status of the job. This field only applies to updating an ingestion job and is ignored when creating jobs. You cannot update a deletion job. The default desired execution status is running for jobs that should run to completion. Otherwise, specify the value canceled to cancel an ingestion job. If an unsupported value is supplied, Polaris raises a 400 Bad Request error.

Responses

Request samples

Content type
application/json
{
  • "desiredExecutionStatus": "running"
}

Response samples

Content type
application/json
Example
{
  • "createdBy": {
    },
  • "createdTimestamp": "2021-06-06T00:00:00.000Z",
  • "desiredExecutionStatus": "running",
  • "executionStatus": "pending",
  • "health": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "lastModifiedBy": {
    },
  • "lastUpdatedTimestamp": "2021-06-06T00:00:00.000Z",
  • "spec": {
    },
  • "target": {
    },
  • "type": "batch",
  • "completedTimestamp": "2021-06-06T00:00:00.000Z",
  • "startedTimestamp": "2021-06-06T00:00:00.000Z",
  • "source": {
    },
  • "context": { },
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "query": "string"
}

Get job overall progress

Returns progress for a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "overallProgress": 0.1
}

Get job logs

Returns logs for a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

Get job metrics

Returns detailed metrics about a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "totals": {
    }
}

Reset job to apply streaming ingestion offset

Resets a streaming ingestion job. This resets the point from which Polaris ingests streaming data to readFromPoint set in current streaming ingestion jobs. Only applies when there was a previous streaming ingestion job that used the same topic or stream name for the same target table. For more information, see Reset streaming job offset.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get job execution status

Returns the execution status for a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

Server-generated job ID.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "executionStatus": "pending"
}

Update job execution status

Updates the execution status of a job.

Use this request to cancel any ingestion job in progress or to suspend and resume a streaming ingestion job.

You can't update data deletion jobs.

Prefer this method over Updating a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

Server-generated job ID.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Request Body schema: application/json
required

A request to update the job's execution status.

desiredExecutionStatus
required
string (DesiredJobExecutionStatusV2)
Default: "running"
Enum: "running" "canceled" "suspended"

Desired execution status of the job. This field only applies to updating an ingestion job and is ignored when creating jobs. You cannot update a deletion job. The default desired execution status is running for jobs that should run to completion. Otherwise, specify the value canceled to cancel an ingestion job. If an unsupported value is supplied, Polaris raises a 400 Bad Request error.

Responses

Request samples

Content type
application/json
{
  • "desiredExecutionStatus": "running"
}

Response samples

Content type
application/json
{
  • "executionStatus": "pending"
}

Query v1

Submit and manage queries.

The Query API has resources to perform synchronous or asynchronous queries. Synchronous (sync) queries are short running (highly concurrent) and low latency. Asynchronous (async) queries are long running, high latency, and high throughput.

Sync queries target precached data including real-time streaming data. Async queries target all data, including any data only in deep storage. Data only in deep storage is offloaded from precache due to one or more cached storage policies. To add or update a storage policy on a table, see storagePolicy in Update a table.

You can query data that's already ingested into Imply Polaris. You can't use the Query API for ingesting data. To ingest data, see Create a job.

For a guide on querying data, see Query data by API.

Polaris projects created after July 1, 2024 have the async query feature enabled by default. If your project was created before July 1, 2024, contact your Polaris support representative to enable the feature.

Query precached data

Submits a SQL query against precached data including real-time streaming data. Returns a JSON object with the query results.

This request does not query data that’s offloaded from precache and only in deep storage. Polaris directly returns query results in the HTTP response body.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

Request Body schema: application/json
required

The SQL query and additional properties to control query execution and result format.

query
required
string

The SQL query.

object

JSON object containing optional SQL query context parameters, such as to set the query ID, time zone, and whether to use an approximation algorithm for distinct count. For supported parameters, see Druid SQL query context.

header
boolean
Default: false

Boolean value that determines whether to return information on column names. When set to true, Polaris returns the column names as the first row of the results. To also get information on the column types, set typesHeader or sqlTypesHeader to true.

parameters
Array of objects

List of Druid SQL query parameters for parameterized queries. Each parameter in the array should be a JSON object containing the parameter's SQL data type and parameter value.

For example, the following query returns results with timestamps later than 2019-08-21 00:00:00:

{
  "query": "SELECT \"col1\" FROM \"myTable\" WHERE __time > ? AND ARRAY_CONTAINS(?, \"col1\")",
  "parameters": [
    {
      "type": "TIMESTAMP",
      "value": "2019-08-21 00:00:00"
    },
    {
      "type": "ARRAY",
      "value": [-25.7, null, 36.85]
    }
  ]
}
resultFormat
string (ResultFormat)
Default: "object"
Enum: "object" "array" "objectLines" "arrayLines" "csv"

String that indicates the format to return query results. Select one of the following formats:

  • object: Returns a JSON array of JSON objects with the HTTP response header Content-Type: application/json. Object field names match the columns returned by the SQL query in the same order as the SQL query.

  • array: Returns a JSON array of JSON arrays with the HTTP response header Content-Type: application/json. Each inner array has elements matching the columns returned by the SQL query, in order.

  • objectLines: Returns newline-delimited JSON objects with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • arrayLines: Returns newline-delimited JSON arrays with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • csv: Returns comma-separated values with one row per line. Sent with the HTTP response header Content-Type: text/csv.

    Druid uses double quotes to escape individual field values. For example, a value with a comma returns "A,B". If the field value contains a double quote character, Druid escapes it with a second double quote character. For example, foo"bar becomes foo""bar. This format includes a single trailing newline character so you can detect a truncated response.

sqlTypesHeader
boolean
Default: false

Adds SQL type information in the header. Requires header to be set to true. For compatibility, Druid returns the HTTP header X-Druid-SQL-Header-Included: yes when all of the following conditions are met:

  • The header property is set to true.
  • The version of Druid supports typesHeader and sqlTypesHeader, regardless of whether either property is set.
typesHeader
boolean
Default: false

Adds runtime type information in the header. Requires header to be set to true. Complex types, like sketches, will be reported as COMPLEX<typeName> if a particular complex type name is known for that field, or as COMPLEX if the particular type name is unknown or mixed.

Responses

Request samples

Content type
application/json
{
  • "query": "SELECT \"__time\", \"val\" FROM \"polaris_table\" WHERE \"foo\" = 'bar'",
  • "resultFormat": "array",
  • "header": false,
  • "typesHeader": false,
  • "sqlTypesHeader": false,
  • "context": {
    },
  • "parameters": [
    ]
}

Response samples

Content type
application/json
[
  • [
    ]
]

Query all data asynchronously

Submits a SQL query against real-time data as well as data in deep storage.

Queries precached data as well as data offloaded from precache. The response body doesn't return query results. To get query results, see Get results for an async query.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

Request Body schema: application/json
required

The SQL query and additional properties to control query execution and result format.

query
required
string

The SQL query.

object

JSON object containing optional SQL query context parameters, such as to set the query ID, time zone, and whether to use an approximation algorithm for distinct count. For supported parameters, see Druid SQL query context.

header
boolean
Default: false

Boolean value that determines whether to return information on column names. When set to true, Polaris returns the column names as the first row of the results. To also get information on the column types, set typesHeader or sqlTypesHeader to true.

parameters
Array of objects

List of Druid SQL query parameters for parameterized queries. Each parameter in the array should be a JSON object containing the parameter's SQL data type and parameter value.

For example, the following query returns results with timestamps later than 2019-08-21 00:00:00:

{
  "query": "SELECT \"col1\" FROM \"myTable\" WHERE __time > ? AND ARRAY_CONTAINS(?, \"col1\")",
  "parameters": [
    {
      "type": "TIMESTAMP",
      "value": "2019-08-21 00:00:00"
    },
    {
      "type": "ARRAY",
      "value": [-25.7, null, 36.85]
    }
  ]
}
resultFormat
string (ResultFormat)
Default: "object"
Enum: "object" "array" "objectLines" "arrayLines" "csv"

String that indicates the format to return query results. Select one of the following formats:

  • object: Returns a JSON array of JSON objects with the HTTP response header Content-Type: application/json. Object field names match the columns returned by the SQL query in the same order as the SQL query.

  • array: Returns a JSON array of JSON arrays with the HTTP response header Content-Type: application/json. Each inner array has elements matching the columns returned by the SQL query, in order.

  • objectLines: Returns newline-delimited JSON objects with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • arrayLines: Returns newline-delimited JSON arrays with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • csv: Returns comma-separated values with one row per line. Sent with the HTTP response header Content-Type: text/csv.

    Druid uses double quotes to escape individual field values. For example, a value with a comma returns "A,B". If the field value contains a double quote character, Druid escapes it with a second double quote character. For example, foo"bar becomes foo""bar. This format includes a single trailing newline character so you can detect a truncated response.

sqlTypesHeader
boolean
Default: false

Adds SQL type information in the header. Requires header to be set to true. For compatibility, Druid returns the HTTP header X-Druid-SQL-Header-Included: yes when all of the following conditions are met:

  • The header property is set to true.
  • The version of Druid supports typesHeader and sqlTypesHeader, regardless of whether either property is set.
typesHeader
boolean
Default: false

Adds runtime type information in the header. Requires header to be set to true. Complex types, like sketches, will be reported as COMPLEX<typeName> if a particular complex type name is known for that field, or as COMPLEX if the particular type name is unknown or mixed.

Responses

Request samples

Content type
application/json
{
  • "query": "SELECT \"__time\", \"val\" FROM \"polaris_table\" WHERE \"foo\" = 'bar'",
  • "resultFormat": "array",
  • "header": false,
  • "typesHeader": false,
  • "sqlTypesHeader": false,
  • "context": {
    },
  • "parameters": [
    ]
}

Response samples

Content type
application/json
{
  • "queryId": "string",
  • "state": "ACCEPTED",
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "schema": [
    ],
  • "durationMs": 36000,
  • "result": {
    },
  • "stages": { },
  • "counters": { },
  • "warnings": { }
}

Get results for an async query

Retrieves results for a completed query.

This request doesn’t return results when the async query performs an ingestion job, that is, a query starting with INSERT or REPLACE. To get the status of the ingestion job, see Get job execution status.

Results are separated into pages, so you can use the optional page parameter to refine the results you get. Polaris returns information about the composition of each page and its page number (id).

For information about pages, see Get status of an async query. If you don't specify a page number, the API returns all results sequentially in the same response.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

queryId
required
string (QueryId)
Example: query-94f176eb-3cc8-489e-919e-1135802b8c55

The server-generated ID of the query.

query Parameters
id
string (ResultFormat)
Default: "object"
Enum: "object" "array" "objectLines" "arrayLines" "csv"
Example: id=array

Defines the format in which the results are presented.

page
integer

Fetch results based on page numbers. If not specified, all results are returned sequentially starting from page 0 to N in the same response.

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Get status of an async query

Retrieves information about the query associated with the given query ID.

The response matches the response from submitting an async query if the query is accepted or running.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

queryId
required
string (QueryId)
Example: query-94f176eb-3cc8-489e-919e-1135802b8c55

The server-generated ID of the query.

query Parameters
detail
boolean
Default: false

Fetch additional details about the query, which includes the information about different stages, counters for each stage, and any warnings.

Responses

Response samples

Content type
application/json
{
  • "queryId": "string",
  • "state": "ACCEPTED",
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "schema": [
    ],
  • "durationMs": 36000,
  • "result": {
    },
  • "stages": { },
  • "counters": { },
  • "warnings": { }
}

Cancel an async query

Cancels a running or accepted async query.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

queryId
required
string (QueryId)
Example: query-94f176eb-3cc8-489e-919e-1135802b8c55

The server-generated ID of the query.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errorCode": "string",
  • "persona": "string",
  • "category": "DEFENSIVE",
  • "errorMessage": "string",
  • "context": { }
}

Tables v1

Manage tables and their schemas.

List all tables in a project

Returns all available tables for a project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

query Parameters
partitioningGranularity
string
Default: "day"
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "week" "month" "quarter" "year" "all"
Example: partitioningGranularity=day

Filters results by the partitioning granularity specified.

segmentCount
integer <int64> >= 0

Filters results by the number of segments specified.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a table

Creates a table.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

Request Body schema: application/json
required

A table to be created.

name
required
string (TableName) [ 1 .. 255 ] characters

The unique, immutable name of the table.

type
required
string (TableType)

The type of table. Once set, you cannot change a table's type. The following table types are supported:

  • detail - A detail table is a standard table that stores each ingested record as a row in the table.
  • aggregate - An aggregate table combines multiple rows based on dimension values and the table's timeResolution, resulting in a condensed data set for improved query performance. See Introduction to data rollup for more details.
version
required
integer <int64> (TableVersion)
Default: 0

The version number of the table. Newly created tables are always initialized at version 0. Do not provide the version number when creating a table. When updating a table, provide the current table version number. If the version number in the request is not the current version, Polaris raises a 409 Conflict error. In that case, retrieve the latest version and retry the request to avoid concurrently conflicting changes.

clusteringColumns
Array of strings (TableClusteringColumns)

Table columns to use for clustering. Polaris sorts table columns within the partition based on their order in this array.

For aggregate tables, only dimensions (not measures) are supported for clustering. If a nonexistent column is specified, Polaris raises a 400 Bad Request error.

For more information, see Clustering.

description
string or null (TableDescription)

The table's description, limited to 1000 characters.

partitioningGranularity
string (TablePartitioningGranularity)
Default: "day"
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "week" "month" "quarter" "year" "all"

The time partitioning of the table. The all granularity groups all data into a single bucket. The week granularity is deprecated. You can't create a new table with the time partitioning set to week. A table sourced by a lookup can only use all partitioning. You can’t change this setting on a table that’s actively used by a lookup.

object (GranularityPayload)

The table's rollup granularity. Determines how to bucket data across the time dimension, such as aggregating data by hour. When set, queryGranularity overrides the rollup granularity in timeResolution.

Array of objects (AggregateTableColumn)
Default: []

The table's schema. The order of the elements determines the order of the columns in the Polaris UI and in SELECT * SQL queries.

schemaMode
string (TableSchemaMode)
Enum: "flexible" "strict"

The table's schema enforcement mode. For more information, see Introduction to tables.

object (TableStoragePolicy)

Policy specifying the time range of data to retain or precache.

  • The retain storage policy determines how long to keep data after which it is deleted.
  • The cached storage policy determines how long to keep data precached. Outside of the cached policy time range, data isn't precached and only resides in lower cost deep storage.

By default, Polaris retains all data and precaches all data. You can’t set a custom storage policy for a table that’s actively used by a lookup. For more information, see Data lifecycle management.

timeResolution
string (TimeResolution)
Default: "millisecond"
Enum: "millisecond" "second" "minute" "fifteen_minute" "thirty_minute" "hour" "day" "week" "month" "quarter" "year" "all"

The table's rollup granularity. See Introduction to data rollup for more details.

You can specify a variable duration or a time zone and origin for a period-type query granularity. When set, queryGranularity overrides the rollup granularity in timeResolution.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "clusteringColumns": [
    ],
  • "description": "Description of example-table",
  • "partitioningGranularity": "day",
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Response samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "availability": "available",
  • "clusteringColumns": [
    ],
  • "createdByUser": {
    },
  • "createdOnTimestamp": "2019-08-24T14:15:22Z",
  • "description": "Description of example-table",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2021-06-06T00:00:00.000Z",
  • "partitioningGranularity": "day",
  • "queryableSchema": [ ],
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "segmentCompactedBytes": 12345678,
  • "segmentCount": 0,
  • "segmentTotalBytes": 12345678,
  • "precachedDataSizeBytes": 12345678,
  • "totalDataSizeBytes": 12345678,
  • "totalRows": 1234,
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Get table details

Returns information for a single table.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

tableName
required
string (TableName) [ 1 .. 255 ] characters
Example: example-table

Name of the table for which to get information.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "availability": "available",
  • "clusteringColumns": [
    ],
  • "createdByUser": {
    },
  • "createdOnTimestamp": "2019-08-24T14:15:22Z",
  • "description": "Description of example-table",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2021-06-06T00:00:00.000Z",
  • "partitioningGranularity": "day",
  • "queryableSchema": [ ],
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "segmentCompactedBytes": 12345678,
  • "segmentCount": 0,
  • "segmentTotalBytes": 12345678,
  • "precachedDataSizeBytes": 12345678,
  • "totalDataSizeBytes": 12345678,
  • "totalRows": 1234,
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Update a table

Updates a table.

You can add columns to a table's schema at any point. You can only update or remove columns from a table's schema when the table is empty and has no active ingestion jobs.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

tableName
required
string (TableName) [ 1 .. 255 ] characters
Example: example-table

Name of the table for which to get information.

Request Body schema: application/json
required

The table to be updated.

name
required
string (TableName) [ 1 .. 255 ] characters

The unique, immutable name of the table.

type
required
string (TableType)

The type of table. Once set, you cannot change a table's type. The following table types are supported:

  • detail - A detail table is a standard table that stores each ingested record as a row in the table.
  • aggregate - An aggregate table combines multiple rows based on dimension values and the table's timeResolution, resulting in a condensed data set for improved query performance. See Introduction to data rollup for more details.
version
required
integer <int64> (TableVersion)
Default: 0

The version number of the table. Newly created tables are always initialized at version 0. Do not provide the version number when creating a table. When updating a table, provide the current table version number. If the version number in the request is not the current version, Polaris raises a 409 Conflict error. In that case, retrieve the latest version and retry the request to avoid concurrently conflicting changes.

clusteringColumns
Array of strings (TableClusteringColumns)

Table columns to use for clustering. Polaris sorts table columns within the partition based on their order in this array.

For aggregate tables, only dimensions (not measures) are supported for clustering. If a nonexistent column is specified, Polaris raises a 400 Bad Request error.

For more information, see Clustering.

description
string or null (TableDescription)

The table's description, limited to 1000 characters.

partitioningGranularity
string (TablePartitioningGranularity)
Default: "day"
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "week" "month" "quarter" "year" "all"

The time partitioning of the table. The all granularity groups all data into a single bucket. The week granularity is deprecated. You can't create a new table with the time partitioning set to week. A table sourced by a lookup can only use all partitioning. You can’t change this setting on a table that’s actively used by a lookup.

object (GranularityPayload)

The table's rollup granularity. Determines how to bucket data across the time dimension, such as aggregating data by hour. When set, queryGranularity overrides the rollup granularity in timeResolution.

Array of objects (AggregateTableColumn)
Default: []

The table's schema. The order of the elements determines the order of the columns in the Polaris UI and in SELECT * SQL queries.

schemaMode
string (TableSchemaMode)
Enum: "flexible" "strict"

The table's schema enforcement mode. For more information, see Introduction to tables.

object (TableStoragePolicy)

Policy specifying the time range of data to retain or precache.

  • The retain storage policy determines how long to keep data after which it is deleted.
  • The cached storage policy determines how long to keep data precached. Outside of the cached policy time range, data isn't precached and only resides in lower cost deep storage.

By default, Polaris retains all data and precaches all data. You can’t set a custom storage policy for a table that’s actively used by a lookup. For more information, see Data lifecycle management.

timeResolution
string (TimeResolution)
Default: "millisecond"
Enum: "millisecond" "second" "minute" "fifteen_minute" "thirty_minute" "hour" "day" "week" "month" "quarter" "year" "all"

The table's rollup granularity. See Introduction to data rollup for more details.

You can specify a variable duration or a time zone and origin for a period-type query granularity. When set, queryGranularity overrides the rollup granularity in timeResolution.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "clusteringColumns": [
    ],
  • "description": "Description of example-table",
  • "partitioningGranularity": "day",
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Response samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "availability": "available",
  • "clusteringColumns": [
    ],
  • "createdByUser": {
    },
  • "createdOnTimestamp": "2019-08-24T14:15:22Z",
  • "description": "Description of example-table",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2021-06-06T00:00:00.000Z",
  • "partitioningGranularity": "day",
  • "queryableSchema": [ ],
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "segmentCompactedBytes": 12345678,
  • "segmentCount": 0,
  • "segmentTotalBytes": 12345678,
  • "precachedDataSizeBytes": 12345678,
  • "totalDataSizeBytes": 12345678,
  • "totalRows": 1234,
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Get table's unused segments

Returns list of unused segments for the specified table matching query parameters given.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

tableName
required
string (TableName) [ 1 .. 255 ] characters
Example: example-table

Name of the table for which to get information.

query Parameters
interval
string

Filters results for unused segments by the time interval specified.

lastSegmentId
string (SegmentId)
Example: lastSegmentId=Example_Table_2023-01-01T00:00:00.000Z_2023-01-02T00:00:00.000Z_2023-10-01T00:00:00.000Z

The segmentId to use as a marker from which to search. If sortOrder = ASC or not specified, all segments returned will have a segmentId that is strictly greater than this. If sortOrder = DESC, all segments returned will have a segmentId that is strictly less than this.

limit
integer
Default: 100

The maximum number of segments to return in the response.

sortOrder
string (SortOrder)
Default: "DESC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order with which the resulting segments should be sorted with respect to their segmentId. If not specified, the order of the results is not guaranteed.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Alerts v1

Create and manage alerts and the conditions that trigger them. See Set up alerts for information on managing alerts in the Polaris UI.

List all alerts

Returns all alerts.

Authorizations:
bearerAuthapiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create an alert

Creates an alert.

Authorizations:
bearerAuthapiKeyAuth
Request Body schema: application/json
required
checkFrequency
required
string <duration>

How often Polaris evaluates alert criteria, expressed as an ISO 8601 duration.

required
Array of objects (AlertCondition)

Specify one or more conditions to trigger your alert. If you specify more than one condition, you can set the conditionOperation property to determine whether one or all conditions must be true to trigger the alert.

dataCube
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

owner
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

timeFrame
required
string <duration>

Controls the amount of data Polaris considers when evaluating the alert criteria based upon a time interval, expressed as an ISO 8601 duration.

title
required
string

Alert title to display in the Polaris UI, and in emails and webhooks.

any (AccessList)

Configure user access to the asset.

object (Compare)

A comparison for Pivot Classic data cubes.

conditionOperation
string (ConditionOperation)
Enum: "and" "or"

Select whether one or all conditions must be true to trigger the alert.

dateTimeToStart
string

Date and time to start triggering alerts. The timezone is UTC.

disabled
boolean

Disables the alert. Polaris doesn't evaluate disabled alerts or trigger notifications.

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to notify when the alert triggers.

object (Filter)

Filter to apply to a query.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

instance
string

Optional instance ID to use for the alert configuration.

https://docs.imply.io/latest/managing-data-cubes/#instances
LatestDataStrategy (string) or string (LatestDataStrategyOverride)
any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendEmailToRecipients
boolean

Send email notifications to the alert recipients when the alert triggers.

severity
string (Severity)
Default: "info"
Enum: "info" "warning" "error" "ok"

Severity determines the alert's color and icon in the Polaris UI.

(SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)
type
string (AlertType)
Enum: "overall" "within-split"

Specify overall to evaluate against a measure, and within-split to evaluate against a dimension.

Array of objects (Webhook)

Webhooks to call when the alert is triggered.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Get alert details

Returns details of a specified alert.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Update an alert

Updates the details of an alert with a specified ID. You must provide all properties you want to retain in the alert, even if you don't want to update them. Polaris recreates the alert with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Request Body schema: application/json
required

Alert ID.

checkFrequency
required
string <duration>

How often Polaris evaluates alert criteria, expressed as an ISO 8601 duration.

required
Array of objects (AlertCondition)

Specify one or more conditions to trigger your alert. If you specify more than one condition, you can set the conditionOperation property to determine whether one or all conditions must be true to trigger the alert.

dataCube
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

owner
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

timeFrame
required
string <duration>

Controls the amount of data Polaris considers when evaluating the alert criteria based upon a time interval, expressed as an ISO 8601 duration.

title
required
string

Alert title to display in the Polaris UI, and in emails and webhooks.

any (AccessList)

Configure user access to the asset.

object (Compare)

A comparison for Pivot Classic data cubes.

conditionOperation
string (ConditionOperation)
Enum: "and" "or"

Select whether one or all conditions must be true to trigger the alert.

dateTimeToStart
string

Date and time to start triggering alerts. The timezone is UTC.

disabled
boolean

Disables the alert. Polaris doesn't evaluate disabled alerts or trigger notifications.

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to notify when the alert triggers.

object (Filter)

Filter to apply to a query.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

instance
string

Optional instance ID to use for the alert configuration.

https://docs.imply.io/latest/managing-data-cubes/#instances
LatestDataStrategy (string) or string (LatestDataStrategyOverride)
any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendEmailToRecipients
boolean

Send email notifications to the alert recipients when the alert triggers.

severity
string (Severity)
Default: "info"
Enum: "info" "warning" "error" "ok"

Severity determines the alert's color and icon in the Polaris UI.

(SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)
type
string (AlertType)
Enum: "overall" "within-split"

Specify overall to evaluate against a measure, and within-split to evaluate against a dimension.

Array of objects (Webhook)

Webhooks to call when the alert is triggered.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Update specified alert properties

Updates the specified properties of an alert. Any properties omitted from the request retain their previous values. Polaris creates a new alert if the supplied alert ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Request Body schema: application/merge-patch+json
required

Alert updates

any (AccessList)

Configure user access to the asset.

checkFrequency
string <duration>

How often Polaris evaluates alert criteria, expressed as an ISO 8601 duration.

object (Compare)

A comparison for Pivot Classic data cubes.

conditionOperation
string (ConditionOperation)
Enum: "and" "or"

Select whether one or all conditions must be true to trigger the alert.

Array of objects (AlertCondition)

Specify one or more conditions to trigger your alert. If you specify more than one condition, you can set the conditionOperation property to determine whether one or all conditions must be true to trigger the alert.

dataCube
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

dateTimeToStart
string

Date and time to start triggering alerts. The timezone is UTC.

disabled
boolean

Disables the alert. Polaris doesn't evaluate disabled alerts or trigger notifications.

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to notify when the alert triggers.

object (Filter)

Filter to apply to a query.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

instance
string

Optional instance ID to use for the alert configuration.

https://docs.imply.io/latest/managing-data-cubes/#instances
LatestDataStrategy (string) or string (LatestDataStrategyOverride)
owner
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendEmailToRecipients
boolean

Send email notifications to the alert recipients when the alert triggers.

severity
string (Severity)
Default: "info"
Enum: "info" "warning" "error" "ok"

Severity determines the alert's color and icon in the Polaris UI.

(SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)
timeFrame
string <duration>

Controls the amount of data Polaris considers when evaluating the alert criteria based upon a time interval, expressed as an ISO 8601 duration.

title
string

Alert title to display in the Polaris UI, and in emails and webhooks.

type
string (AlertType)
Enum: "overall" "within-split"

Specify overall to evaluate against a measure, and within-split to evaluate against a dimension.

Array of objects (Webhook)

Webhooks to call when the alert is triggered.

property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Delete an alert

Deletes an alert.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Get alert evaluations

Returns all evaluations for an alert.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Get alert evaluation details

Returns information for a single alert evaluation.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
evaluationId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Evaluation ID.

id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "alertId": "wikipedia-1234",
  • "alert": {
    },
  • "triggerDate": "2019-08-24T14:15:22Z",
  • "maxDate": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "summaries": [
    ],
  • "errors": [
    ],
  • "queries": [
    ]
}

Collections v1

Create, edit, and delete Polaris collections. See Collections and favorites for information on managing collections in the Polaris UI.

List all collections

Returns all collections in a specified project.

Authorizations:
bearerAuth
path Parameters
projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a collection

Creates a collection in a specified project.

Authorizations:
bearerAuth
path Parameters
projectId
required
string

Project ID.

Request Body schema: application/json
required
name
required
string (CollectionName)

Name of the collection.

description
string (CollectionDescription)

Description of the collection.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Get a collection

Returns a single collection in a specified project.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Update specified collection properties

Updates a collection name and/or description.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Request Body schema: application/merge-patch+json
required

The collection updates

description
string (CollectionDescription)

Description of the collection.

name
string (CollectionName)

Name of the collection.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Delete a collection

Deletes a single collection in a specified project.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Add assets to a collection

Adds specified assets to a collection.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)