Skip to content

Lists

Service for managing lists.

Lists are spreadsheet-like collections of people, companies, or opportunities.

Source code in affinity/services/lists.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
class ListService:
    """
    Service for managing lists.

    Lists are spreadsheet-like collections of people, companies, or opportunities.
    """

    def __init__(self, client: HTTPClient):
        self._client = client
        self._resolve_cache: dict[tuple[str, ListType | None], AffinityList | None] = {}

    def entries(self, list_id: ListId) -> ListEntryService:
        """
        Get a ListEntryService for a specific list.

        This is the explicit path for retrieving "full row" data via list entries.
        """
        return ListEntryService(self._client, list_id)

    # =========================================================================
    # List Operations (V2 for read, V1 for write)
    # =========================================================================

    def list(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[AffinityList]:
        """
        Get all lists accessible to you.

        Args:
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).

        Returns:
            Paginated list of lists (without field metadata)
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            data = self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = self._client.get("/lists", params=params or None)

        return PaginatedResponse[AffinityList](
            data=[
                _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
            ],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    def pages(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> Iterator[PaginatedResponse[AffinityList]]:
        """
        Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

        This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
        """
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = self.list(limit=limit) if cursor is None else self.list(cursor=cursor)
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = self.list(cursor=next_cursor)

    def all(self) -> Iterator[AffinityList]:
        """Iterate through all accessible lists."""

        def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
            if next_url:
                data = self._client.get_url(next_url)
                return PaginatedResponse[AffinityList](
                    data=[
                        _safe_model_validate(AffinityList, list_item)
                        for list_item in data.get("data", [])
                    ],
                    pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
                )
            return self.list()

        return PageIterator(fetch_page)

    def iter(self) -> Iterator[AffinityList]:
        """
        Auto-paginate all lists.

        Alias for `all()` (FR-006 public contract).
        """
        return self.all()

    def get(self, list_id: ListId) -> AffinityList:
        """
        Get a single list by ID.

        Includes field metadata for the list.

        Note: Uses V1 API because V2's listSize field is undocumented and
        returns incorrect values (often 0 for non-empty lists).
        """
        data = self._client.get(f"/lists/{list_id}", v1=True)
        return _safe_model_validate(AffinityList, data)

    def resolve(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> AffinityList | None:
        """
        Find a single list by name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Results are cached in-memory on this service instance. If you call this frequently,
          reuse the client, or persist the resolved `ListId` in your own configuration.

        If multiple matches exist, returns the first match in server-provided order.
        """
        key = (name.lower(), list_type)
        if key in self._resolve_cache:
            return self._resolve_cache[key]

        for item in self.all():
            if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
                self._resolve_cache[key] = item
                return item

        self._resolve_cache[key] = None
        return None

    def resolve_all(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> builtins.list[AffinityList]:
        """
        Find all lists matching a name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Unlike `resolve()`, this does not cache results.
        """
        matches: builtins.list[AffinityList] = []
        name_lower = name.lower()
        for item in self.all():
            if item.name.lower() != name_lower:
                continue
            if list_type is not None and item.type != list_type:
                continue
            matches.append(item)
        return matches

    def create(self, data: ListCreate) -> AffinityList:
        """
        Create a new list.

        Uses V1 API.
        """
        payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
        if not data.additional_permissions:
            payload.pop("additional_permissions", None)

        result = self._client.post("/lists", json=payload, v1=True)

        # Invalidate cache
        if self._client.cache:
            self._client.cache.invalidate_prefix("list")
        self._resolve_cache.clear()

        return _safe_model_validate(AffinityList, result)

    # =========================================================================
    # Field Operations
    # =========================================================================

    def get_fields(
        self,
        list_id: ListId,
        *,
        field_types: Sequence[FieldType] | None = None,
    ) -> builtins.list[FieldMetadata]:
        """
        Get fields (columns) for a list.

        Includes list-specific, global, enriched, and relationship intelligence fields.
        Cached for performance.
        """
        params: dict[str, Any] = {}
        if field_types:
            params["fieldTypes"] = [field_type.value for field_type in field_types]

        data = self._client.get(
            f"/lists/{list_id}/fields",
            params=params or None,
            cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
            cache_ttl=300,
        )

        return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

    # =========================================================================
    # Saved View Operations
    # =========================================================================

    def get_saved_views(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[SavedView]:
        """
        Get saved views for a list.

        Args:
            list_id: List id for the initial request.
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            cursor_list_id = _saved_views_list_id_from_cursor(cursor)
            if cursor_list_id is not None and int(list_id) != cursor_list_id:
                raise ValueError(
                    f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                    f"requested list_id is {int(list_id)}"
                )
            data = self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

        return PaginatedResponse[SavedView](
            data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    def saved_views_pages(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> Iterator[PaginatedResponse[SavedView]]:
        """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = (
            self.get_saved_views(list_id, limit=limit)
            if cursor is None
            else self.get_saved_views(list_id, cursor=cursor)
        )
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = self.get_saved_views(list_id, cursor=next_cursor)

    def saved_views_all(self, list_id: ListId) -> Iterator[SavedView]:
        """Iterate all saved views for a list."""
        for page in self.saved_views_pages(list_id):
            yield from page.data

    def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
        """Get a single saved view."""
        data = self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
        return _safe_model_validate(SavedView, data)

all() -> Iterator[AffinityList]

Iterate through all accessible lists.

Source code in affinity/services/lists.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def all(self) -> Iterator[AffinityList]:
    """Iterate through all accessible lists."""

    def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
        if next_url:
            data = self._client.get_url(next_url)
            return PaginatedResponse[AffinityList](
                data=[
                    _safe_model_validate(AffinityList, list_item)
                    for list_item in data.get("data", [])
                ],
                pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
            )
        return self.list()

    return PageIterator(fetch_page)

create(data: ListCreate) -> AffinityList

Create a new list.

Uses V1 API.

Source code in affinity/services/lists.py 
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
def create(self, data: ListCreate) -> AffinityList:
    """
    Create a new list.

    Uses V1 API.
    """
    payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
    if not data.additional_permissions:
        payload.pop("additional_permissions", None)

    result = self._client.post("/lists", json=payload, v1=True)

    # Invalidate cache
    if self._client.cache:
        self._client.cache.invalidate_prefix("list")
    self._resolve_cache.clear()

    return _safe_model_validate(AffinityList, result)

entries(list_id: ListId) -> ListEntryService

Get a ListEntryService for a specific list.

This is the explicit path for retrieving "full row" data via list entries.

Source code in affinity/services/lists.py 
 96
 97
 98
 99
100
101
102
def entries(self, list_id: ListId) -> ListEntryService:
    """
    Get a ListEntryService for a specific list.

    This is the explicit path for retrieving "full row" data via list entries.
    """
    return ListEntryService(self._client, list_id)

get(list_id: ListId) -> AffinityList

Get a single list by ID.

Includes field metadata for the list.

Note: Uses V1 API because V2's listSize field is undocumented and returns incorrect values (often 0 for non-empty lists).

Source code in affinity/services/lists.py 
200
201
202
203
204
205
206
207
208
209
210
def get(self, list_id: ListId) -> AffinityList:
    """
    Get a single list by ID.

    Includes field metadata for the list.

    Note: Uses V1 API because V2's listSize field is undocumented and
    returns incorrect values (often 0 for non-empty lists).
    """
    data = self._client.get(f"/lists/{list_id}", v1=True)
    return _safe_model_validate(AffinityList, data)

get_fields(list_id: ListId, *, field_types: Sequence[FieldType] | None = None) -> builtins.list[FieldMetadata]

Get fields (columns) for a list.

Includes list-specific, global, enriched, and relationship intelligence fields. Cached for performance.

Source code in affinity/services/lists.py 
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def get_fields(
    self,
    list_id: ListId,
    *,
    field_types: Sequence[FieldType] | None = None,
) -> builtins.list[FieldMetadata]:
    """
    Get fields (columns) for a list.

    Includes list-specific, global, enriched, and relationship intelligence fields.
    Cached for performance.
    """
    params: dict[str, Any] = {}
    if field_types:
        params["fieldTypes"] = [field_type.value for field_type in field_types]

    data = self._client.get(
        f"/lists/{list_id}/fields",
        params=params or None,
        cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
        cache_ttl=300,
    )

    return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

get_saved_view(list_id: ListId, view_id: SavedViewId) -> SavedView

Get a single saved view.

Source code in affinity/services/lists.py 
391
392
393
394
def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
    """Get a single saved view."""
    data = self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
    return _safe_model_validate(SavedView, data)

get_saved_views(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[SavedView]

Get saved views for a list.

Parameters:

Name Type Description Default
list_id ListId

List id for the initial request.

 required
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None
Source code in affinity/services/lists.py 
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
def get_saved_views(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[SavedView]:
    """
    Get saved views for a list.

    Args:
        list_id: List id for the initial request.
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        cursor_list_id = _saved_views_list_id_from_cursor(cursor)
        if cursor_list_id is not None and int(list_id) != cursor_list_id:
            raise ValueError(
                f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                f"requested list_id is {int(list_id)}"
            )
        data = self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

    return PaginatedResponse[SavedView](
        data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

iter() -> Iterator[AffinityList]

Auto-paginate all lists.

Alias for all() (FR-006 public contract).

Source code in affinity/services/lists.py 
192
193
194
195
196
197
198
def iter(self) -> Iterator[AffinityList]:
    """
    Auto-paginate all lists.

    Alias for `all()` (FR-006 public contract).
    """
    return self.all()

list(*, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[AffinityList]

Get all lists accessible to you.

Parameters:

Name Type Description Default
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None

Returns:

Type Description
PaginatedResponse[AffinityList]

Paginated list of lists (without field metadata)
Source code in affinity/services/lists.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def list(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[AffinityList]:
    """
    Get all lists accessible to you.

    Args:
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).

    Returns:
        Paginated list of lists (without field metadata)
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        data = self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = self._client.get("/lists", params=params or None)

    return PaginatedResponse[AffinityList](
        data=[
            _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
        ],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

pages(*, limit: int | None = None, cursor: str | None = None) -> Iterator[PaginatedResponse[AffinityList]]

Iterate list pages (not items), yielding PaginatedResponse[AffinityList].

This is useful for ETL scripts that want checkpoint/resume via page.next_cursor.

Source code in affinity/services/lists.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
def pages(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> Iterator[PaginatedResponse[AffinityList]]:
    """
    Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

    This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
    """
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = self.list(limit=limit) if cursor is None else self.list(cursor=cursor)
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = self.list(cursor=next_cursor)

resolve(*, name: str, list_type: ListType | None = None) -> AffinityList | None

Find a single list by name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Results are cached in-memory on this service instance. If you call this frequently, reuse the client, or persist the resolved ListId in your own configuration.

If multiple matches exist, returns the first match in server-provided order.

Source code in affinity/services/lists.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def resolve(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> AffinityList | None:
    """
    Find a single list by name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Results are cached in-memory on this service instance. If you call this frequently,
      reuse the client, or persist the resolved `ListId` in your own configuration.

    If multiple matches exist, returns the first match in server-provided order.
    """
    key = (name.lower(), list_type)
    if key in self._resolve_cache:
        return self._resolve_cache[key]

    for item in self.all():
        if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
            self._resolve_cache[key] = item
            return item

    self._resolve_cache[key] = None
    return None

resolve_all(*, name: str, list_type: ListType | None = None) -> builtins.list[AffinityList]

Find all lists matching a name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Unlike resolve(), this does not cache results.

Source code in affinity/services/lists.py 
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
def resolve_all(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> builtins.list[AffinityList]:
    """
    Find all lists matching a name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Unlike `resolve()`, this does not cache results.
    """
    matches: builtins.list[AffinityList] = []
    name_lower = name.lower()
    for item in self.all():
        if item.name.lower() != name_lower:
            continue
        if list_type is not None and item.type != list_type:
            continue
        matches.append(item)
    return matches

saved_views_all(list_id: ListId) -> Iterator[SavedView]

Iterate all saved views for a list.

Source code in affinity/services/lists.py 
386
387
388
389
def saved_views_all(self, list_id: ListId) -> Iterator[SavedView]:
    """Iterate all saved views for a list."""
    for page in self.saved_views_pages(list_id):
        yield from page.data

saved_views_pages(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> Iterator[PaginatedResponse[SavedView]]

Iterate saved view pages, yielding PaginatedResponse[SavedView].

Source code in affinity/services/lists.py 
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
def saved_views_pages(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> Iterator[PaginatedResponse[SavedView]]:
    """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = (
        self.get_saved_views(list_id, limit=limit)
        if cursor is None
        else self.get_saved_views(list_id, cursor=cursor)
    )
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = self.get_saved_views(list_id, cursor=next_cursor)

Async list operations (TR-009).

Source code in affinity/services/lists.py 
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
class AsyncListService:
    """Async list operations (TR-009)."""

    def __init__(self, client: AsyncHTTPClient):
        self._client = client
        self._resolve_cache: dict[tuple[str, ListType | None], AffinityList | None] = {}

    def entries(self, list_id: ListId) -> AsyncListEntryService:
        """
        Get an AsyncListEntryService for a specific list.

        This is the explicit path for retrieving "full row" data via list entries.
        """
        return AsyncListEntryService(self._client, list_id)

    async def list(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[AffinityList]:
        """
        Get all lists accessible to you.

        Args:
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).

        Returns:
            Paginated list of lists (without field metadata)
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            data = await self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = await self._client.get("/lists", params=params or None)
        return PaginatedResponse[AffinityList](
            data=[
                _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
            ],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    async def pages(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> AsyncIterator[PaginatedResponse[AffinityList]]:
        """
        Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

        This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
        """
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = await self.list(limit=limit) if cursor is None else await self.list(cursor=cursor)
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = await self.list(cursor=next_cursor)

    def all(self) -> AsyncIterator[AffinityList]:
        """Iterate through all accessible lists."""

        async def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
            if next_url:
                data = await self._client.get_url(next_url)
                return PaginatedResponse[AffinityList](
                    data=[
                        _safe_model_validate(AffinityList, list_item)
                        for list_item in data.get("data", [])
                    ],
                    pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
                )
            return await self.list()

        return AsyncPageIterator(fetch_page)

    def iter(self) -> AsyncIterator[AffinityList]:
        """
        Auto-paginate all lists.

        Alias for `all()` (FR-006 public contract).
        """
        return self.all()

    # =========================================================================
    # Saved View Operations
    # =========================================================================

    async def get_saved_views(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> PaginatedResponse[SavedView]:
        """
        Get saved views for a list.

        Args:
            list_id: List id for the initial request.
            limit: Maximum results per page.
            cursor: Cursor to resume pagination (opaque; obtained from prior responses).
        """
        if cursor is not None:
            if limit is not None:
                raise ValueError(
                    "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                    "context. Start a new pagination sequence without a cursor to change "
                    "parameters."
                )
            cursor_list_id = _saved_views_list_id_from_cursor(cursor)
            if cursor_list_id is not None and int(list_id) != cursor_list_id:
                raise ValueError(
                    f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                    f"requested list_id is {int(list_id)}"
                )
            data = await self._client.get_url(cursor)
        else:
            if limit is not None and limit <= 0:
                raise ValueError("'limit' must be > 0")
            params: dict[str, Any] = {}
            if limit is not None:
                params["limit"] = limit
            data = await self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

        return PaginatedResponse[SavedView](
            data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
            pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
        )

    async def saved_views_pages(
        self,
        list_id: ListId,
        *,
        limit: int | None = None,
        cursor: str | None = None,
    ) -> AsyncIterator[PaginatedResponse[SavedView]]:
        """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
        if cursor is not None and limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
                "Start a new pagination sequence without a cursor to change parameters."
            )
        requested_cursor = cursor
        page = (
            await self.get_saved_views(list_id, limit=limit)
            if cursor is None
            else await self.get_saved_views(list_id, cursor=cursor)
        )
        while True:
            yield page
            if not page.has_next:
                return
            next_cursor = page.next_cursor
            if next_cursor is None or next_cursor == requested_cursor:
                return
            requested_cursor = next_cursor
            page = await self.get_saved_views(list_id, cursor=next_cursor)

    async def saved_views_all(self, list_id: ListId) -> AsyncIterator[SavedView]:
        """Iterate all saved views for a list."""
        async for page in self.saved_views_pages(list_id):
            for item in page.data:
                yield item

    async def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
        """Get a single saved view."""
        data = await self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
        return _safe_model_validate(SavedView, data)

    async def get(self, list_id: ListId) -> AffinityList:
        """
        Get a single list by ID.

        Includes field metadata for the list.

        Note: Uses V1 API because V2's listSize field is undocumented and
        returns incorrect values (often 0 for non-empty lists).
        """
        data = await self._client.get(f"/lists/{list_id}", v1=True)
        return _safe_model_validate(AffinityList, data)

    async def resolve(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> AffinityList | None:
        """
        Find a single list by name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Results are cached in-memory on this service instance. If you call this frequently,
          reuse the client, or persist the resolved `ListId` in your own configuration.

        If multiple matches exist, returns the first match in server-provided order.
        """
        key = (name.lower(), list_type)
        if key in self._resolve_cache:
            return self._resolve_cache[key]

        async for item in self.all():
            if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
                self._resolve_cache[key] = item
                return item

        self._resolve_cache[key] = None
        return None

    async def resolve_all(
        self,
        *,
        name: str,
        list_type: ListType | None = None,
    ) -> builtins.list[AffinityList]:
        """
        Find all lists matching a name (optionally filtered by type).

        Notes:
        - This iterates list pages client-side (the API does not expose a list-search endpoint).
        - Unlike `resolve()`, this does not cache results.
        """
        matches: builtins.list[AffinityList] = []
        name_lower = name.lower()
        async for item in self.all():
            if item.name.lower() != name_lower:
                continue
            if list_type is not None and item.type != list_type:
                continue
            matches.append(item)
        return matches

    # =========================================================================
    # Write Operations (V1 API)
    # =========================================================================

    async def create(self, data: ListCreate) -> AffinityList:
        """
        Create a new list.

        Uses V1 API.
        """
        payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
        if not data.additional_permissions:
            payload.pop("additional_permissions", None)

        result = await self._client.post("/lists", json=payload, v1=True)

        if self._client.cache:
            self._client.cache.invalidate_prefix("list")
        self._resolve_cache.clear()

        return _safe_model_validate(AffinityList, result)

    # =========================================================================
    # Field Operations
    # =========================================================================

    async def get_fields(
        self,
        list_id: ListId,
        *,
        field_types: Sequence[FieldType] | None = None,
    ) -> builtins.list[FieldMetadata]:
        """
        Get fields (columns) for a list.

        Includes list-specific, global, enriched, and relationship intelligence fields.
        Cached for performance.
        """
        params: dict[str, Any] = {}
        if field_types:
            params["fieldTypes"] = [field_type.value for field_type in field_types]

        data = await self._client.get(
            f"/lists/{list_id}/fields",
            params=params or None,
            cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
            cache_ttl=300,
        )

        return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

all() -> AsyncIterator[AffinityList]

Iterate through all accessible lists.

Source code in affinity/services/lists.py 
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
def all(self) -> AsyncIterator[AffinityList]:
    """Iterate through all accessible lists."""

    async def fetch_page(next_url: str | None) -> PaginatedResponse[AffinityList]:
        if next_url:
            data = await self._client.get_url(next_url)
            return PaginatedResponse[AffinityList](
                data=[
                    _safe_model_validate(AffinityList, list_item)
                    for list_item in data.get("data", [])
                ],
                pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
            )
        return await self.list()

    return AsyncPageIterator(fetch_page)

create(data: ListCreate) -> AffinityList async

Create a new list.

Uses V1 API.

Source code in affinity/services/lists.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
async def create(self, data: ListCreate) -> AffinityList:
    """
    Create a new list.

    Uses V1 API.
    """
    payload = data.model_dump(mode="json", exclude_none=True, exclude_unset=True)
    if not data.additional_permissions:
        payload.pop("additional_permissions", None)

    result = await self._client.post("/lists", json=payload, v1=True)

    if self._client.cache:
        self._client.cache.invalidate_prefix("list")
    self._resolve_cache.clear()

    return _safe_model_validate(AffinityList, result)

entries(list_id: ListId) -> AsyncListEntryService

Get an AsyncListEntryService for a specific list.

This is the explicit path for retrieving "full row" data via list entries.

Source code in affinity/services/lists.py 
916
917
918
919
920
921
922
def entries(self, list_id: ListId) -> AsyncListEntryService:
    """
    Get an AsyncListEntryService for a specific list.

    This is the explicit path for retrieving "full row" data via list entries.
    """
    return AsyncListEntryService(self._client, list_id)

get(list_id: ListId) -> AffinityList async

Get a single list by ID.

Includes field metadata for the list.

Note: Uses V1 API because V2's listSize field is undocumented and returns incorrect values (often 0 for non-empty lists).

Source code in affinity/services/lists.py 
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
async def get(self, list_id: ListId) -> AffinityList:
    """
    Get a single list by ID.

    Includes field metadata for the list.

    Note: Uses V1 API because V2's listSize field is undocumented and
    returns incorrect values (often 0 for non-empty lists).
    """
    data = await self._client.get(f"/lists/{list_id}", v1=True)
    return _safe_model_validate(AffinityList, data)

get_fields(list_id: ListId, *, field_types: Sequence[FieldType] | None = None) -> builtins.list[FieldMetadata] async

Get fields (columns) for a list.

Includes list-specific, global, enriched, and relationship intelligence fields. Cached for performance.

Source code in affinity/services/lists.py 
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
async def get_fields(
    self,
    list_id: ListId,
    *,
    field_types: Sequence[FieldType] | None = None,
) -> builtins.list[FieldMetadata]:
    """
    Get fields (columns) for a list.

    Includes list-specific, global, enriched, and relationship intelligence fields.
    Cached for performance.
    """
    params: dict[str, Any] = {}
    if field_types:
        params["fieldTypes"] = [field_type.value for field_type in field_types]

    data = await self._client.get(
        f"/lists/{list_id}/fields",
        params=params or None,
        cache_key=f"list_{list_id}_fields:{','.join(field_types or [])}",
        cache_ttl=300,
    )

    return [_safe_model_validate(FieldMetadata, f) for f in data.get("data", [])]

get_saved_view(list_id: ListId, view_id: SavedViewId) -> SavedView async

Get a single saved view.

Source code in affinity/services/lists.py 
1096
1097
1098
1099
async def get_saved_view(self, list_id: ListId, view_id: SavedViewId) -> SavedView:
    """Get a single saved view."""
    data = await self._client.get(f"/lists/{list_id}/saved-views/{view_id}")
    return _safe_model_validate(SavedView, data)

get_saved_views(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[SavedView] async

Get saved views for a list.

Parameters:

Name Type Description Default
list_id ListId

List id for the initial request.

 required
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None
Source code in affinity/services/lists.py 
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
async def get_saved_views(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[SavedView]:
    """
    Get saved views for a list.

    Args:
        list_id: List id for the initial request.
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        cursor_list_id = _saved_views_list_id_from_cursor(cursor)
        if cursor_list_id is not None and int(list_id) != cursor_list_id:
            raise ValueError(
                f"Cursor does not match list_id: cursor is for list {cursor_list_id}, "
                f"requested list_id is {int(list_id)}"
            )
        data = await self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = await self._client.get(f"/lists/{list_id}/saved-views", params=params or None)

    return PaginatedResponse[SavedView](
        data=[_safe_model_validate(SavedView, v) for v in data.get("data", [])],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

iter() -> AsyncIterator[AffinityList]

Auto-paginate all lists.

Alias for all() (FR-006 public contract).

Source code in affinity/services/lists.py 
1007
1008
1009
1010
1011
1012
1013
def iter(self) -> AsyncIterator[AffinityList]:
    """
    Auto-paginate all lists.

    Alias for `all()` (FR-006 public contract).
    """
    return self.all()

list(*, limit: int | None = None, cursor: str | None = None) -> PaginatedResponse[AffinityList] async

Get all lists accessible to you.

Parameters:

Name Type Description Default
limit int | None

Maximum results per page.

 None
cursor str | None

Cursor to resume pagination (opaque; obtained from prior responses).

 None

Returns:

Type Description
PaginatedResponse[AffinityList]

Paginated list of lists (without field metadata)
Source code in affinity/services/lists.py 
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
async def list(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> PaginatedResponse[AffinityList]:
    """
    Get all lists accessible to you.

    Args:
        limit: Maximum results per page.
        cursor: Cursor to resume pagination (opaque; obtained from prior responses).

    Returns:
        Paginated list of lists (without field metadata)
    """
    if cursor is not None:
        if limit is not None:
            raise ValueError(
                "Cannot combine 'cursor' with other parameters; cursor encodes all query "
                "context. Start a new pagination sequence without a cursor to change "
                "parameters."
            )
        data = await self._client.get_url(cursor)
    else:
        if limit is not None and limit <= 0:
            raise ValueError("'limit' must be > 0")
        params: dict[str, Any] = {}
        if limit is not None:
            params["limit"] = limit
        data = await self._client.get("/lists", params=params or None)
    return PaginatedResponse[AffinityList](
        data=[
            _safe_model_validate(AffinityList, list_item) for list_item in data.get("data", [])
        ],
        pagination=_safe_model_validate(PaginationInfo, data.get("pagination", {})),
    )

pages(*, limit: int | None = None, cursor: str | None = None) -> AsyncIterator[PaginatedResponse[AffinityList]] async

Iterate list pages (not items), yielding PaginatedResponse[AffinityList].

This is useful for ETL scripts that want checkpoint/resume via page.next_cursor.

Source code in affinity/services/lists.py 
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
async def pages(
    self,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> AsyncIterator[PaginatedResponse[AffinityList]]:
    """
    Iterate list pages (not items), yielding `PaginatedResponse[AffinityList]`.

    This is useful for ETL scripts that want checkpoint/resume via `page.next_cursor`.
    """
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = await self.list(limit=limit) if cursor is None else await self.list(cursor=cursor)
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = await self.list(cursor=next_cursor)

resolve(*, name: str, list_type: ListType | None = None) -> AffinityList | None async

Find a single list by name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Results are cached in-memory on this service instance. If you call this frequently, reuse the client, or persist the resolved ListId in your own configuration.

If multiple matches exist, returns the first match in server-provided order.

Source code in affinity/services/lists.py 
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
async def resolve(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> AffinityList | None:
    """
    Find a single list by name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Results are cached in-memory on this service instance. If you call this frequently,
      reuse the client, or persist the resolved `ListId` in your own configuration.

    If multiple matches exist, returns the first match in server-provided order.
    """
    key = (name.lower(), list_type)
    if key in self._resolve_cache:
        return self._resolve_cache[key]

    async for item in self.all():
        if item.name.lower() == name.lower() and (list_type is None or item.type == list_type):
            self._resolve_cache[key] = item
            return item

    self._resolve_cache[key] = None
    return None

resolve_all(*, name: str, list_type: ListType | None = None) -> builtins.list[AffinityList] async

Find all lists matching a name (optionally filtered by type).

Notes: - This iterates list pages client-side (the API does not expose a list-search endpoint). - Unlike resolve(), this does not cache results.

Source code in affinity/services/lists.py 
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
async def resolve_all(
    self,
    *,
    name: str,
    list_type: ListType | None = None,
) -> builtins.list[AffinityList]:
    """
    Find all lists matching a name (optionally filtered by type).

    Notes:
    - This iterates list pages client-side (the API does not expose a list-search endpoint).
    - Unlike `resolve()`, this does not cache results.
    """
    matches: builtins.list[AffinityList] = []
    name_lower = name.lower()
    async for item in self.all():
        if item.name.lower() != name_lower:
            continue
        if list_type is not None and item.type != list_type:
            continue
        matches.append(item)
    return matches

saved_views_all(list_id: ListId) -> AsyncIterator[SavedView] async

Iterate all saved views for a list.

Source code in affinity/services/lists.py 
1090
1091
1092
1093
1094
async def saved_views_all(self, list_id: ListId) -> AsyncIterator[SavedView]:
    """Iterate all saved views for a list."""
    async for page in self.saved_views_pages(list_id):
        for item in page.data:
            yield item

saved_views_pages(list_id: ListId, *, limit: int | None = None, cursor: str | None = None) -> AsyncIterator[PaginatedResponse[SavedView]] async

Iterate saved view pages, yielding PaginatedResponse[SavedView].

Source code in affinity/services/lists.py 
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
async def saved_views_pages(
    self,
    list_id: ListId,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> AsyncIterator[PaginatedResponse[SavedView]]:
    """Iterate saved view pages, yielding `PaginatedResponse[SavedView]`."""
    if cursor is not None and limit is not None:
        raise ValueError(
            "Cannot combine 'cursor' with other parameters; cursor encodes all query context. "
            "Start a new pagination sequence without a cursor to change parameters."
        )
    requested_cursor = cursor
    page = (
        await self.get_saved_views(list_id, limit=limit)
        if cursor is None
        else await self.get_saved_views(list_id, cursor=cursor)
    )
    while True:
        yield page
        if not page.has_next:
            return
        next_cursor = page.next_cursor
        if next_cursor is None or next_cursor == requested_cursor:
            return
        requested_cursor = next_cursor
        page = await self.get_saved_views(list_id, cursor=next_cursor)