attio-js
Version:
Developer-friendly & type-safe JS/TS SDK based on the official OpenAPI spec of Attio.
396 lines (293 loc) • 26.9 kB
Markdown
# Lists
(*lists*)
## Overview
Lists are used to model a particular process. A list contains many records of a single object type, where each record is represented by an entry. Entries contain their own data from attributes defined on the list and also data from their parent record. See our [data model guide](/docs/data-model) for more information.
### Available Operations
* [listAll](#listall) - List all lists
* [create](#create) - Create a list
* [get](#get) - Get a list
* [update](#update) - Update a list
## listAll
List all lists that your access token has access to. lists are returned in the order that they are sorted in the sidebar.
Required scopes: `list_configuration:read`.
### Example Usage
```typescript
import { Attio } from "attio-js";
const attio = new Attio({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const result = await attio.lists.listAll();
// Handle the result
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { AttioCore } from "attio-js/core.js";
import { listsListAll } from "attio-js/funcs/listsListAll.js";
// Use `AttioCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const attio = new AttioCore({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const res = await listsListAll(attio);
if (!res.ok) {
throw res.error;
}
const { value: result } = res;
// Handle the result
console.log(result);
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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.GetV2ListsResponse](../../models/operations/getv2listsresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| --------------- | --------------- | --------------- |
| errors.APIError | 4XX, 5XX | \*/\* |
## create
Creates a new list.
Once you have your list, add attributes to it using the [Create attribute](/reference/post_v2-target-identifier-attributes) API, and add records to it using the [Add records to list](/reference/post_v2-lists-list-entries) API.
New lists must specify which records can be added with the `parent_object` parameter which accepts either an object slug or an object ID. Permissions for the list are controlled with the `workspace_access` and `workspace_member_access` parameters.
Please note that new lists must have either `workspace_access` set to `"full-access"` or one or more element of `workspace_member_access` with a `"full-access"` level. It is also possible to receive a `403` billing error if your workspace is not on a plan that supports either advanced workspace or workspace member-level access for lists.
Required scopes: `list_configuration:read-write`.
### Example Usage
```typescript
import { Attio } from "attio-js";
const attio = new Attio({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const result = await attio.lists.create({
data: {
name: "Enterprise Sales",
apiSlug: "enterprise_sales",
parentObject: "people",
workspaceAccess: "read-and-write",
workspaceMemberAccess: [
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
],
},
});
// Handle the result
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { AttioCore } from "attio-js/core.js";
import { listsCreate } from "attio-js/funcs/listsCreate.js";
// Use `AttioCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const attio = new AttioCore({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const res = await listsCreate(attio, {
data: {
name: "Enterprise Sales",
apiSlug: "enterprise_sales",
parentObject: "people",
workspaceAccess: "read-and-write",
workspaceMemberAccess: [
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
],
},
});
if (!res.ok) {
throw res.error;
}
const { value: result } = res;
// Handle the result
console.log(result);
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.PostV2ListsRequest](../../models/operations/postv2listsrequest.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.PostV2ListsResponse](../../models/operations/postv2listsresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| ------------------------------------- | ------------------------------------- | ------------------------------------- |
| errors.PostV2ListsInvalidRequestError | 400 | application/json |
| errors.BillingError | 403 | application/json |
| errors.PostV2ListsNotFoundError | 404 | application/json |
| errors.APIError | 4XX, 5XX | \*/\* |
## get
Gets a single list in your workspace that your access token has access to.
Required scopes: `list_configuration:read`.
### Example Usage
```typescript
import { Attio } from "attio-js";
const attio = new Attio({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const result = await attio.lists.get({
list: "33ebdbe9-e529-47c9-b894-0ba25e9c15c0",
});
// Handle the result
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { AttioCore } from "attio-js/core.js";
import { listsGet } from "attio-js/funcs/listsGet.js";
// Use `AttioCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const attio = new AttioCore({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const res = await listsGet(attio, {
list: "33ebdbe9-e529-47c9-b894-0ba25e9c15c0",
});
if (!res.ok) {
throw res.error;
}
const { value: result } = res;
// Handle the result
console.log(result);
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.GetV2ListsListRequest](../../models/operations/getv2listslistrequest.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.GetV2ListsListResponse](../../models/operations/getv2listslistresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
| errors.GetV2ListsListNotFoundError | 404 | application/json |
| errors.APIError | 4XX, 5XX | \*/\* |
## update
Updates an existing list. Permissions for the list are controlled with the `workspace_access` and `workspace_member_access` parameters. Please note that lists must have either `workspace_access` set to `"full-access"` or one or more element of `workspace_member_access` with a `"full-access"` level. It is also possible to receive a `403` billing error if your workspace is not on a plan that supports either advanced workspace or workspace member level access for lists. Changing the parent object of a list is not possible through the API as it can have unintended side-effects that should be considered carefully. If you wish to carry out a parent object change you should do so through the UI.
Required scopes: `list_configuration:read-write`.
### Example Usage
```typescript
import { Attio } from "attio-js";
const attio = new Attio({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const result = await attio.lists.update({
list: "33ebdbe9-e529-47c9-b894-0ba25e9c15c0",
requestBody: {
data: {
name: "Enterprise Sales",
apiSlug: "enterprise_sales",
workspaceAccess: "read-and-write",
workspaceMemberAccess: [
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
],
},
},
});
// Handle the result
console.log(result);
}
run();
```
### Standalone function
The standalone function version of this method:
```typescript
import { AttioCore } from "attio-js/core.js";
import { listsUpdate } from "attio-js/funcs/listsUpdate.js";
// Use `AttioCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const attio = new AttioCore({
apiKey: process.env["ATTIO_API_KEY"] ?? "",
});
async function run() {
const res = await listsUpdate(attio, {
list: "33ebdbe9-e529-47c9-b894-0ba25e9c15c0",
requestBody: {
data: {
name: "Enterprise Sales",
apiSlug: "enterprise_sales",
workspaceAccess: "read-and-write",
workspaceMemberAccess: [
{
workspaceMemberId: "50cf242c-7fa3-4cad-87d0-75b1af71c57b",
level: "read-and-write",
},
],
},
},
});
if (!res.ok) {
throw res.error;
}
const { value: result } = res;
// Handle the result
console.log(result);
}
run();
```
### Parameters
| Parameter | Type | Required | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request` | [operations.PatchV2ListsListRequest](../../models/operations/patchv2listslistrequest.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.PatchV2ListsListResponse](../../models/operations/patchv2listslistresponse.md)\>**
### Errors
| Error Type | Status Code | Content Type |
| ------------------------------------- | ------------------------------------- | ------------------------------------- |
| errors.PostV2ListsInvalidRequestError | 400 | application/json |
| errors.GetV2ListsListNotFoundError | 404 | application/json |
| errors.APIError | 4XX, 5XX | \*/\* |