archastro.platform.v1.resources.custom_objects

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: c863576cd3e0
  4
  5from __future__ import annotations
  6
  7import builtins
  8from datetime import datetime
  9from typing import Any, Required, TypedDict
 10
 11from pydantic import BaseModel, Field
 12
 13from ...runtime.http_client import HttpClient, SyncHttpClient
 14from ...types.common import CustomObject, CustomObjectListResponse
 15
 16
 17class CustomObjectCreateInputAclAddItem(TypedDict, total=False):
 18    actions: Required[list[str]]
 19    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 20    principal: str | None
 21    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 22    principal_type: Required[str]
 23    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 24
 25
 26class CustomObjectCreateInputAclGrantsItem(TypedDict, total=False):
 27    actions: Required[list[str]]
 28    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 29    principal: str | None
 30    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 31    principal_type: Required[str]
 32    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 33
 34
 35class CustomObjectCreateInputAclRemoveItem(TypedDict, total=False):
 36    principal: str | None
 37    'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.'
 38    principal_type: Required[str]
 39    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 40
 41
 42class CustomObjectCreateInputAcl(TypedDict, total=False):
 43    add: list[CustomObjectCreateInputAclAddItem] | None
 44    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
 45    grants: list[CustomObjectCreateInputAclGrantsItem] | None
 46    "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."
 47    remove: list[CustomObjectCreateInputAclRemoveItem] | None
 48    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
 49
 50
 51class CustomObjectCreateInput(TypedDict, total=False):
 52    "Create a custom object"
 53
 54    acl: CustomObjectCreateInputAcl | None
 55    "Access control list for the custom object. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone."
 56    agent: str | None
 57    "Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied."
 58    config: str | None
 59    "Config ID (`cfg_...`) that resolves to the target schema. Provide one of `type`, `schema_key`, or `config`."
 60    fields: dict[str, Any] | None
 61    "Key-value map of field values for the new object. Must conform to the schema's field definitions. Omit to create an object with all fields at their default or null values."
 62    org: str | None
 63    "Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects."
 64    schema_key: str | None
 65    "Legacy alias for `type` (schema `lookup_key`). Prefer `type` on new clients. Provide one of `type`, `schema_key`, or `config`."
 66    system: bool | None
 67    "When `true`, creates a system-owned object with no team, user, or agent owner. Requires elevated API credentials; returns 403 if the caller lacks permission."
 68    team: str | None
 69    "Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`."
 70    type: str | None
 71    "Schema type identifier (`lookup_key`) that defines the object's shape and validation rules. Preferred over the legacy `schema_key` / `config` aliases."
 72    upsert: bool | None
 73    "When `true` and the schema declares a `row_key`, updates the existing object at that key for the same owner instead of returning 409 Conflict. Returns HTTP 200 on update and 201 on create."
 74    user: str | None
 75    "User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set."
 76
 77
 78class CustomObjectReplaceInputAclAddItem(TypedDict, total=False):
 79    actions: Required[list[str]]
 80    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 81    principal: str | None
 82    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 83    principal_type: Required[str]
 84    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 85
 86
 87class CustomObjectReplaceInputAclGrantsItem(TypedDict, total=False):
 88    actions: Required[list[str]]
 89    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
 90    principal: str | None
 91    'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.'
 92    principal_type: Required[str]
 93    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
 94
 95
 96class CustomObjectReplaceInputAclRemoveItem(TypedDict, total=False):
 97    principal: str | None
 98    'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.'
 99    principal_type: Required[str]
100    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
101
102
103class CustomObjectReplaceInputAcl(TypedDict, total=False):
104    add: list[CustomObjectReplaceInputAclAddItem] | None
105    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
106    grants: list[CustomObjectReplaceInputAclGrantsItem] | None
107    "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`."
108    remove: list[CustomObjectReplaceInputAclRemoveItem] | None
109    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
110
111
112class CustomObjectReplaceInput(TypedDict, total=False):
113    "Update a custom object"
114
115    acl: CustomObjectReplaceInputAcl | None
116    "Updated access control list. Supports full replacement via `grants` or targeted `add`/`remove` operations."
117    field_ops: dict[str, Any] | None
118    "Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both `fields` and `field_ops`."
119    fields: dict[str, Any] | None
120    "Key-value map of field values to merge into the object. Only the supplied keys are affected."
121    type: str | None
122    "Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only."
123
124
125class CustomObjectDeleteResponse(BaseModel):
126    """
127    Successful response
128    """
129
130    deleted: bool = Field(..., description="Always `true` when the deletion succeeds.")
131    id: str = Field(..., description="ID of the deleted custom object (`cobj_...`).")
132
133
134class CustomObjectReplaceResponseDataAclAddItem(BaseModel):
135    actions: list[str] = Field(
136        ...,
137        description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.',
138    )
139    principal: str | None = Field(
140        default=None,
141        description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.',
142    )
143    principal_type: str = Field(
144        ...,
145        description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
146    )
147
148
149class CustomObjectReplaceResponseDataAclGrantsItem(BaseModel):
150    actions: list[str] = Field(
151        ...,
152        description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.',
153    )
154    principal: str | None = Field(
155        default=None,
156        description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.',
157    )
158    principal_type: str = Field(
159        ...,
160        description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
161    )
162
163
164class CustomObjectReplaceResponseDataAclRemoveItem(BaseModel):
165    principal: str | None = Field(
166        default=None,
167        description='The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.',
168    )
169    principal_type: str = Field(
170        ...,
171        description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
172    )
173
174
175class CustomObjectReplaceResponseDataAcl(BaseModel):
176    add: list[CustomObjectReplaceResponseDataAclAddItem] | None = Field(
177        default=None,
178        description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.",
179    )
180    grants: list[CustomObjectReplaceResponseDataAclGrantsItem] | None = Field(
181        default=None,
182        description="Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.",
183    )
184    remove: list[CustomObjectReplaceResponseDataAclRemoveItem] | None = Field(
185        default=None,
186        description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.",
187    )
188
189
190class CustomObjectReplaceResponseData(BaseModel):
191    acl: CustomObjectReplaceResponseDataAcl | None = Field(
192        default=None,
193        description="Access control list governing read and write access to this custom object. Only returned to resource owners and privileged or organization-admin viewers; `null` for everyone else.",
194    )
195    created_at: datetime | None = Field(
196        default=None, description="When the custom object was created (ISO 8601)."
197    )
198    fields: dict[str, Any] | None = Field(
199        default=None,
200        description="Map of field names to their current values as defined by the object's schema type.",
201    )
202    id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).")
203    org: str | None = Field(
204        default=None, description="ID of the organization this object belongs to (`org_...`)."
205    )
206    row_key: str | None = Field(
207        default=None,
208        description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.",
209    )
210    sandbox: str | None = Field(
211        default=None,
212        description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.",
213    )
214    schema_type: str | None = Field(
215        default=None,
216        description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.",
217    )
218    team: str | None = Field(
219        default=None,
220        description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.",
221    )
222    updated_at: datetime | None = Field(
223        default=None,
224        description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.",
225    )
226    user: str | None = Field(
227        default=None,
228        description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.",
229    )
230    version: int | None = Field(
231        default=None,
232        description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.",
233    )
234
235
236class CustomObjectReplaceResponse(BaseModel):
237    """
238    Successful response
239    """
240
241    data: CustomObjectReplaceResponseData = Field(
242        ..., description="The custom object after the update has been applied."
243    )
244    meta: dict[str, Any] | None = Field(
245        default=None, description="Version metadata for the updated object."
246    )
247
248
249class AsyncCustomObjectResource:
250    def __init__(self, http: HttpClient):
251        self._http = http
252
253    async def list(
254        self,
255        *,
256        type: str | None = None,
257        schema_key: str | None = None,
258        row_key: str | None = None,
259        sort_key: builtins.list[str] | None = None,
260        team: builtins.list[str] | None = None,
261        user: builtins.list[str] | None = None,
262        agent: builtins.list[str] | None = None,
263        org: builtins.list[str] | None = None,
264        query: str | None = None,
265        search: str | None = None,
266        page: int | None = None,
267        page_size: int | None = None,
268    ) -> CustomObjectListResponse:
269        """
270        List custom objects
271        Returns a paginated list of custom objects visible to the authenticated
272        viewer, ordered by creation time descending. Results span all ownership
273        types (team-owned, user-owned, agent-owned, and system-owned) that the
274        viewer has access to.
275        Filter by schema type with `type` (preferred) or the legacy alias
276        `schema_key`. Use the `row_key` param to perform an exact-match partition
277        lookup. You may additionally supply `sort_key` to narrow within that
278        partition `sort_key` requires `row_key` and the request returns 400 if
279        `sort_key` is provided alone. Owner filters (`team`, `user`, `agent`,
280        `org`) are additive: each accepts an array of IDs (or a single ID, which
281        is wrapped) and returns objects matching any of the supplied values.
282        When `query` is supplied, results are ranked by full-text relevance
283        (descending `ts_rank`) rather than creation time. The legacy `search`
284        param performs a case-insensitive substring match and is retained for
285        developer-namespace clients.
286
287        Args:
288            type: Schema type identifier (`lookup_key`) to filter by. Only objects of this type are returned. Alias of `schema_key`; either name is accepted.
289            schema_key: Legacy alias for `type`. Prefer `type` on new clients. When both are supplied, `type` wins.
290            row_key: Exact `row_key` value to match. When supplied, only objects with this partition key are returned.
291            sort_key: One or more `sort_key` values to match within the `row_key` partition. Requires `row_key` to be set.
292            team: One or more team IDs (`team_...`) to filter by owning team. Returns objects owned by any of the supplied teams.
293            user: One or more user IDs (`user_...`) to filter by owning user. Returns objects owned by any of the supplied users.
294            agent: One or more agent IDs to filter by owning agent. Returns objects owned by any of the supplied agents.
295            org: One or more organization IDs (`org_...`) to filter by. Typically used by admins to query system-owned objects in a specific org.
296            query: Full-text search string matched against the schema's configured search fields. When supplied, results are ordered by relevance score descending instead of creation time descending.
297            search: Case-insensitive substring search applied across the schema type and serialized field values. Deprecated prefer `query` for full-text search. Retained for developer-namespace clients.
298            page: Page number to retrieve (1-indexed). Defaults to `1`.
299            page_size: Number of objects per page. Defaults to `25`; maximum is `100`.
300
301        Returns:
302            Paginated list of custom objects matching the supplied filters.
303        """
304        query: dict[str, object] = {}
305        if type is not None:
306            query["type"] = type
307        if schema_key is not None:
308            query["schema_key"] = schema_key
309        if row_key is not None:
310            query["row_key"] = row_key
311        if sort_key is not None:
312            query["sort_key"] = sort_key
313        if team is not None:
314            query["team"] = team
315        if user is not None:
316            query["user"] = user
317        if agent is not None:
318            query["agent"] = agent
319        if org is not None:
320            query["org"] = org
321        if query is not None:
322            query["query"] = query
323        if search is not None:
324            query["search"] = search
325        if page is not None:
326            query["page"] = page
327        if page_size is not None:
328            query["page_size"] = page_size
329        return await self._http.request(
330            "/api/v1/custom_objects",
331            query=query,
332            response_type=CustomObjectListResponse,
333        )
334
335    async def create(self, input: CustomObjectCreateInput) -> CustomObject:
336        """
337        Create a custom object
338        Creates a new custom object of the given schema type and returns the
339        persisted object. The caller must be authenticated and authorized to create
340        objects of the specified type.
341        Identify the schema with `type` (preferred), or the legacy aliases
342        `schema_key` (lookup key) / `config` (config ID). Exactly one identifier is
343        required; when more than one is supplied, `type` wins over `schema_key`,
344        which wins over `config`.
345        Owner resolution follows a priority order: if `team` is supplied the object
346        is team-owned; if `user` is supplied it is owned by that user; if `agent` is
347        supplied it is agent-owned; otherwise the object is owned by the authenticated
348        user. Pass `system: true` explicitly to force system ownership this requires
349        elevated API credentials and returns 403 if the caller lacks permission.
350        If the schema declares a `row_key` (and optionally a `sort_key`), you may
351        pass `upsert: true` to update an existing object at that key instead of
352        receiving a 409 Conflict. The response status is `200` on an update and
353        `201` on a new create.
354
355        Args:
356            input: Request body.
357            input.acl: Access control list for the custom object. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.
358            input.agent: Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied.
359            input.config: Config ID (`cfg_...`) that resolves to the target schema. Provide one of `type`, `schema_key`, or `config`.
360            input.fields: Key-value map of field values for the new object. Must conform to the schema's field definitions. Omit to create an object with all fields at their default or null values.
361            input.org: Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects.
362            input.schema_key: Legacy alias for `type` (schema `lookup_key`). Prefer `type` on new clients. Provide one of `type`, `schema_key`, or `config`.
363            input.system: When `true`, creates a system-owned object with no team, user, or agent owner. Requires elevated API credentials; returns 403 if the caller lacks permission.
364            input.team: Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`.
365            input.type: Schema type identifier (`lookup_key`) that defines the object's shape and validation rules. Preferred over the legacy `schema_key` / `config` aliases.
366            input.upsert: When `true` and the schema declares a `row_key`, updates the existing object at that key for the same owner instead of returning 409 Conflict. Returns HTTP 200 on update and 201 on create.
367            input.user: User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set.
368
369        Returns:
370            The created (or upserted) custom object.
371        """
372        return await self._http.request(
373            "/api/v1/custom_objects",
374            method="POST",
375            body=input,
376            response_type=CustomObject,
377        )
378
379    async def delete(self, object: str) -> CustomObjectDeleteResponse:
380        """
381        Delete a custom object
382        Permanently deletes the custom object identified by `object`. The caller
383        must be authenticated and have permission to delete the object.
384        On success, returns a confirmation payload containing the deleted object's
385        ID so callers can confirm the deletion without a follow-up fetch.
386        Attempting to delete an object that does not exist or has already been
387        deleted returns 404.
388
389        Args:
390            object: Custom object ID (`cobj_...`) of the object to delete.
391
392        Returns:
393            Successful response
394        """
395        return await self._http.request(
396            f"/api/v1/custom_objects/{object}",
397            method="DELETE",
398            response_type=CustomObjectDeleteResponse,
399        )
400
401    async def get(self, object: str, *, type: str | None = None) -> CustomObject:
402        """
403        Retrieve a custom object
404        Returns a single custom object identified by its ID. The authenticated viewer
405        must have visibility access to the object.
406        Returns 404 if the object does not exist, has been deleted, or is not
407        visible to the viewer.
408
409        Args:
410            object: Custom object ID (`cobj_...`) to retrieve.
411            type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
412
413        Returns:
414            The requested custom object.
415        """
416        query: dict[str, object] = {}
417        if type is not None:
418            query["type"] = type
419        return await self._http.request(
420            f"/api/v1/custom_objects/{object}",
421            query=query,
422            response_type=CustomObject,
423        )
424
425    async def replace(
426        self, object: str, input: CustomObjectReplaceInput
427    ) -> CustomObjectReplaceResponse:
428        """
429        Update a custom object
430        Updates the fields of an existing custom object and returns the updated
431        object along with its new version number. The authenticated viewer must have
432        permission to modify the object.
433        You may supply `fields` (a full or partial key-value map to merge into the
434        object), `field_ops` (granular array operations per field), `acl`, or any
435        compatible combination. The same field name must not appear in both
436        `fields` and `field_ops`, which returns 422. Returns 404 if the object does
437        not exist or has been deleted.
438
439        Args:
440            object: Custom object ID (`cobj_...`) to update.
441            input: Request body.
442            input.acl: Updated access control list. Supports full replacement via `grants` or targeted `add`/`remove` operations.
443            input.field_ops: Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both `fields` and `field_ops`.
444            input.fields: Key-value map of field values to merge into the object. Only the supplied keys are affected.
445            input.type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
446
447        Returns:
448            Successful response
449        """
450        return await self._http.request(
451            f"/api/v1/custom_objects/{object}",
452            method="PUT",
453            body=input,
454            response_type=CustomObjectReplaceResponse,
455        )
456
457
458class CustomObjectResource:
459    def __init__(self, http: SyncHttpClient):
460        self._http = http
461
462    def list(
463        self,
464        *,
465        type: str | None = None,
466        schema_key: str | None = None,
467        row_key: str | None = None,
468        sort_key: builtins.list[str] | None = None,
469        team: builtins.list[str] | None = None,
470        user: builtins.list[str] | None = None,
471        agent: builtins.list[str] | None = None,
472        org: builtins.list[str] | None = None,
473        query: str | None = None,
474        search: str | None = None,
475        page: int | None = None,
476        page_size: int | None = None,
477    ) -> CustomObjectListResponse:
478        """
479        List custom objects
480        Returns a paginated list of custom objects visible to the authenticated
481        viewer, ordered by creation time descending. Results span all ownership
482        types (team-owned, user-owned, agent-owned, and system-owned) that the
483        viewer has access to.
484        Filter by schema type with `type` (preferred) or the legacy alias
485        `schema_key`. Use the `row_key` param to perform an exact-match partition
486        lookup. You may additionally supply `sort_key` to narrow within that
487        partition `sort_key` requires `row_key` and the request returns 400 if
488        `sort_key` is provided alone. Owner filters (`team`, `user`, `agent`,
489        `org`) are additive: each accepts an array of IDs (or a single ID, which
490        is wrapped) and returns objects matching any of the supplied values.
491        When `query` is supplied, results are ranked by full-text relevance
492        (descending `ts_rank`) rather than creation time. The legacy `search`
493        param performs a case-insensitive substring match and is retained for
494        developer-namespace clients.
495
496        Args:
497            type: Schema type identifier (`lookup_key`) to filter by. Only objects of this type are returned. Alias of `schema_key`; either name is accepted.
498            schema_key: Legacy alias for `type`. Prefer `type` on new clients. When both are supplied, `type` wins.
499            row_key: Exact `row_key` value to match. When supplied, only objects with this partition key are returned.
500            sort_key: One or more `sort_key` values to match within the `row_key` partition. Requires `row_key` to be set.
501            team: One or more team IDs (`team_...`) to filter by owning team. Returns objects owned by any of the supplied teams.
502            user: One or more user IDs (`user_...`) to filter by owning user. Returns objects owned by any of the supplied users.
503            agent: One or more agent IDs to filter by owning agent. Returns objects owned by any of the supplied agents.
504            org: One or more organization IDs (`org_...`) to filter by. Typically used by admins to query system-owned objects in a specific org.
505            query: Full-text search string matched against the schema's configured search fields. When supplied, results are ordered by relevance score descending instead of creation time descending.
506            search: Case-insensitive substring search applied across the schema type and serialized field values. Deprecated prefer `query` for full-text search. Retained for developer-namespace clients.
507            page: Page number to retrieve (1-indexed). Defaults to `1`.
508            page_size: Number of objects per page. Defaults to `25`; maximum is `100`.
509
510        Returns:
511            Paginated list of custom objects matching the supplied filters.
512        """
513        query: dict[str, object] = {}
514        if type is not None:
515            query["type"] = type
516        if schema_key is not None:
517            query["schema_key"] = schema_key
518        if row_key is not None:
519            query["row_key"] = row_key
520        if sort_key is not None:
521            query["sort_key"] = sort_key
522        if team is not None:
523            query["team"] = team
524        if user is not None:
525            query["user"] = user
526        if agent is not None:
527            query["agent"] = agent
528        if org is not None:
529            query["org"] = org
530        if query is not None:
531            query["query"] = query
532        if search is not None:
533            query["search"] = search
534        if page is not None:
535            query["page"] = page
536        if page_size is not None:
537            query["page_size"] = page_size
538        return self._http.request(
539            "/api/v1/custom_objects",
540            query=query,
541            response_type=CustomObjectListResponse,
542        )
543
544    def create(self, input: CustomObjectCreateInput) -> CustomObject:
545        """
546        Create a custom object
547        Creates a new custom object of the given schema type and returns the
548        persisted object. The caller must be authenticated and authorized to create
549        objects of the specified type.
550        Identify the schema with `type` (preferred), or the legacy aliases
551        `schema_key` (lookup key) / `config` (config ID). Exactly one identifier is
552        required; when more than one is supplied, `type` wins over `schema_key`,
553        which wins over `config`.
554        Owner resolution follows a priority order: if `team` is supplied the object
555        is team-owned; if `user` is supplied it is owned by that user; if `agent` is
556        supplied it is agent-owned; otherwise the object is owned by the authenticated
557        user. Pass `system: true` explicitly to force system ownership this requires
558        elevated API credentials and returns 403 if the caller lacks permission.
559        If the schema declares a `row_key` (and optionally a `sort_key`), you may
560        pass `upsert: true` to update an existing object at that key instead of
561        receiving a 409 Conflict. The response status is `200` on an update and
562        `201` on a new create.
563
564        Args:
565            input: Request body.
566            input.acl: Access control list for the custom object. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.
567            input.agent: Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied.
568            input.config: Config ID (`cfg_...`) that resolves to the target schema. Provide one of `type`, `schema_key`, or `config`.
569            input.fields: Key-value map of field values for the new object. Must conform to the schema's field definitions. Omit to create an object with all fields at their default or null values.
570            input.org: Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects.
571            input.schema_key: Legacy alias for `type` (schema `lookup_key`). Prefer `type` on new clients. Provide one of `type`, `schema_key`, or `config`.
572            input.system: When `true`, creates a system-owned object with no team, user, or agent owner. Requires elevated API credentials; returns 403 if the caller lacks permission.
573            input.team: Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`.
574            input.type: Schema type identifier (`lookup_key`) that defines the object's shape and validation rules. Preferred over the legacy `schema_key` / `config` aliases.
575            input.upsert: When `true` and the schema declares a `row_key`, updates the existing object at that key for the same owner instead of returning 409 Conflict. Returns HTTP 200 on update and 201 on create.
576            input.user: User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set.
577
578        Returns:
579            The created (or upserted) custom object.
580        """
581        return self._http.request(
582            "/api/v1/custom_objects",
583            method="POST",
584            body=input,
585            response_type=CustomObject,
586        )
587
588    def delete(self, object: str) -> CustomObjectDeleteResponse:
589        """
590        Delete a custom object
591        Permanently deletes the custom object identified by `object`. The caller
592        must be authenticated and have permission to delete the object.
593        On success, returns a confirmation payload containing the deleted object's
594        ID so callers can confirm the deletion without a follow-up fetch.
595        Attempting to delete an object that does not exist or has already been
596        deleted returns 404.
597
598        Args:
599            object: Custom object ID (`cobj_...`) of the object to delete.
600
601        Returns:
602            Successful response
603        """
604        return self._http.request(
605            f"/api/v1/custom_objects/{object}",
606            method="DELETE",
607            response_type=CustomObjectDeleteResponse,
608        )
609
610    def get(self, object: str, *, type: str | None = None) -> CustomObject:
611        """
612        Retrieve a custom object
613        Returns a single custom object identified by its ID. The authenticated viewer
614        must have visibility access to the object.
615        Returns 404 if the object does not exist, has been deleted, or is not
616        visible to the viewer.
617
618        Args:
619            object: Custom object ID (`cobj_...`) to retrieve.
620            type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
621
622        Returns:
623            The requested custom object.
624        """
625        query: dict[str, object] = {}
626        if type is not None:
627            query["type"] = type
628        return self._http.request(
629            f"/api/v1/custom_objects/{object}",
630            query=query,
631            response_type=CustomObject,
632        )
633
634    def replace(self, object: str, input: CustomObjectReplaceInput) -> CustomObjectReplaceResponse:
635        """
636        Update a custom object
637        Updates the fields of an existing custom object and returns the updated
638        object along with its new version number. The authenticated viewer must have
639        permission to modify the object.
640        You may supply `fields` (a full or partial key-value map to merge into the
641        object), `field_ops` (granular array operations per field), `acl`, or any
642        compatible combination. The same field name must not appear in both
643        `fields` and `field_ops`, which returns 422. Returns 404 if the object does
644        not exist or has been deleted.
645
646        Args:
647            object: Custom object ID (`cobj_...`) to update.
648            input: Request body.
649            input.acl: Updated access control list. Supports full replacement via `grants` or targeted `add`/`remove` operations.
650            input.field_ops: Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both `fields` and `field_ops`.
651            input.fields: Key-value map of field values to merge into the object. Only the supplied keys are affected.
652            input.type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
653
654        Returns:
655            Successful response
656        """
657        return self._http.request(
658            f"/api/v1/custom_objects/{object}",
659            method="PUT",
660            body=input,
661            response_type=CustomObjectReplaceResponse,
662        )