# Collections
## Overview
Endpoints related to the Collections product
### Available Operations
* [list](#list) - List collections
* [create](#create) - Create a collection
* [delete](#delete) - Delete a collection
* [get](#get) - Get a collection
* [update](#update) - Update a collection
* [listEvents](#listevents) - Get a collection's events
* [aggregate](#aggregate) - Aggregate results for a search query within a collection
* [search](#search) - Run a search query within a collection
## list
List all collections for an organization. Retrieved information includes collection ID, name, query, description, status, and asset count.
This endpoint does not cost credits to execute.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.list({
pageToken: "",
pageSize: 1,
collectionStatuses: [
"populating",
"active",
],
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsList } from "@censys/platform-sdk/funcs/collectionsList.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsList(sdk, {
pageToken: "",
pageSize: 1,
collectionStatuses: [
"populating",
"active",
],
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsList failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsCrudListRequest](../../models/operations/v3collectionscrudlistrequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsCrudListResponse](../../models/operations/v3collectionscrudlistresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |
## create
Create a new collection.
This endpoint does not cost credits to execute.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.create({
crudCreateInputBody: {
description: "Hosts with services with AsyncRAT indicator in cert subject DN",
name: "Hosts services with AsyncRAT indicator",
query: "host.services.cert.parsed.subject_dn: \"asyncrat\"",
},
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsCreate } from "@censys/platform-sdk/funcs/collectionsCreate.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsCreate(sdk, {
crudCreateInputBody: {
description: "Hosts with services with AsyncRAT indicator in cert subject DN",
name: "Hosts services with AsyncRAT indicator",
query: "host.services.cert.parsed.subject_dn: \"asyncrat\"",
},
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsCreate failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsCrudCreateRequest](../../models/operations/v3collectionscrudcreaterequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsCrudCreateResponse](../../models/operations/v3collectionscrudcreateresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403, 409, 412, 422 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |
## delete
Delete a collection.
This endpoint does not cost credits to execute.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.delete({
collectionUid: "11111111-2222-3333-4444-555555555555",
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsDelete } from "@censys/platform-sdk/funcs/collectionsDelete.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsDelete(sdk, {
collectionUid: "11111111-2222-3333-4444-555555555555",
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsDelete failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsCrudDeleteRequest](../../models/operations/v3collectionscruddeleterequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsCrudDeleteResponse](../../models/operations/v3collectionscruddeleteresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403, 404 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |
## get
Retrieve information about a collection. Retrieved information includes its name, query, description, status, and asset count.
This endpoint does not cost credits to execute.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.get({
collectionUid: "11111111-2222-3333-4444-555555555555",
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsGet } from "@censys/platform-sdk/funcs/collectionsGet.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsGet(sdk, {
collectionUid: "11111111-2222-3333-4444-555555555555",
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsGet failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsCrudGetRequest](../../models/operations/v3collectionscrudgetrequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsCrudGetResponse](../../models/operations/v3collectionscrudgetresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403, 404 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |
## update
Update a collection's name, description, and/or query.
This endpoint does not cost credits to execute.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.update({
collectionUid: "11111111-2222-3333-4444-555555555555",
crudUpdateInputBody: {
description: "Hosts with services with AsyncRAT indicator in cert subject DN",
name: "Hosts services with AsyncRAT indicator",
query: "host.services.cert.parsed.subject_dn: \"asyncrat\"",
},
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsUpdate } from "@censys/platform-sdk/funcs/collectionsUpdate.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsUpdate(sdk, {
collectionUid: "11111111-2222-3333-4444-555555555555",
crudUpdateInputBody: {
description: "Hosts with services with AsyncRAT indicator in cert subject DN",
name: "Hosts services with AsyncRAT indicator",
query: "host.services.cert.parsed.subject_dn: \"asyncrat\"",
},
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsUpdate failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsCrudUpdateRequest](../../models/operations/v3collectionscrudupdaterequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsCrudUpdateResponse](../../models/operations/v3collectionscrudupdateresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403, 404, 412 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |
## listEvents
Retrieve the event history for a collection. This includes the addition or removal of assets as well as collection status changes.
This endpoint does not cost credits to execute.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.listEvents({
collectionUid: "11111111-2222-3333-4444-555555555555",
pageSize: 1,
pageToken: "",
startTime: new Date("2025-01-01T00:00:00Z"),
endTime: new Date("2025-01-02T00:00:00Z"),
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsListEvents } from "@censys/platform-sdk/funcs/collectionsListEvents.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsListEvents(sdk, {
collectionUid: "11111111-2222-3333-4444-555555555555",
pageSize: 1,
pageToken: "",
startTime: new Date("2025-01-01T00:00:00Z"),
endTime: new Date("2025-01-02T00:00:00Z"),
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsListEvents failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsListEventsRequest](../../models/operations/v3collectionslisteventsrequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsListEventsResponse](../../models/operations/v3collectionslisteventsresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403, 404, 422 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |
## aggregate
Aggregate results for a Platform search query that targets a collection's assets. This functionality is equivalent to the [Report Builder](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.aggregate({
collectionUid: "11111111-2222-3333-4444-555555555555",
searchAggregateInputBody: {
field: "host.services.port",
numberOfBuckets: 100,
query: "host.services.protocol=SSH",
},
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsAggregate } from "@censys/platform-sdk/funcs/collectionsAggregate.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsAggregate(sdk, {
collectionUid: "11111111-2222-3333-4444-555555555555",
searchAggregateInputBody: {
field: "host.services.port",
numberOfBuckets: 100,
query: "host.services.protocol=SSH",
},
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsAggregate failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsSearchAggregateRequest](../../models/operations/v3collectionssearchaggregaterequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsSearchAggregateResponse](../../models/operations/v3collectionssearchaggregateresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403, 404, 422 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |
## search
Run a search query across a collection's assets. Reference the [documentation on Censys Query Language](https://docs.censys.com/docs/censys-query-language#/) for information about query syntax. Host services that match your search criteria will be returned in a `matched_services` object.
### Example Usage
```typescript
import { SDK } from "@censys/platform-sdk";
const sdk = new SDK({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const result = await sdk.collections.search({
collectionUid: "",
searchQueryInputBody: {
fields: [
"host.ip",
],
pageSize: 1,
query: "host.services: (protocol=SSH and not port: 22)",
},
});
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { SDKCore } from "@censys/platform-sdk/core.js";
import { collectionsSearch } from "@censys/platform-sdk/funcs/collectionsSearch.js";
// Use `SDKCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const sdk = new SDKCore({
organizationId: "11111111-2222-3333-4444-555555555555",
personalAccessToken: "",
});
async function run() {
const res = await collectionsSearch(sdk, {
collectionUid: "",
searchQueryInputBody: {
fields: [
"host.ip",
],
pageSize: 1,
query: "host.services: (protocol=SSH and not port: 22)",
},
});
if (res.ok) {
const { value: result } = res;
console.log(result);
} else {
console.log("collectionsSearch failed:", res.error);
}
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.V3CollectionsSearchQueryRequest](../../models/operations/v3collectionssearchqueryrequest.md) | :heavy_check_mark: | The request object to use for the request. |
| `options` | RequestOptions | :heavy_minus_sign: | Used to set various options for making HTTP requests. |
| `options.fetchOptions` | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) | :heavy_minus_sign: | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
| `options.retries` | [RetryConfig](../../lib/utils/retryconfig.md) | :heavy_minus_sign: | Enables retrying HTTP requests under certain failure conditions. |
### Response
**Promise\<[operations.V3CollectionsSearchQueryResponse](../../models/operations/v3collectionssearchqueryresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| -------------------------- | -------------------------- | -------------------------- |
| errors.AuthenticationError | 401 | application/json |
| errors.ErrorModel | 400, 403, 404, 422 | application/problem+json |
| errors.ErrorModel | 500 | application/problem+json |
| errors.SDKError | 4XX, 5XX | \*/\* |