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: ff8413024cce
  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    expires_at: datetime | None
 61    "Absolute expiry time in RFC 3339 format. Pass null to clear; omit to leave unchanged on update."
 62    fields: dict[str, Any] | None
 63    "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."
 64    org: str | None
 65    "Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects."
 66    schema_key: str | None
 67    "Legacy alias for `type` (schema `lookup_key`). Prefer `type` on new clients. Provide one of `type`, `schema_key`, or `config`."
 68    system: bool | None
 69    "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."
 70    team: str | None
 71    "Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`."
 72    type: str | None
 73    "Schema type identifier (`lookup_key`) that defines the object's shape and validation rules. Preferred over the legacy `schema_key` / `config` aliases."
 74    upsert: bool | None
 75    "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."
 76    user: str | None
 77    "User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set."
 78
 79
 80class CustomObjectPatchInput(TypedDict, total=False):
 81    "Apply numeric patch ops to a custom object"
 82
 83    agent: str | None
 84    "Agent user ID owning the keyed row. At most one owner selector may be present."
 85    create_with: dict[str, Any] | None
 86    "Field values used to create the row when the keyed form finds no existing row. Merged over the key fields before validation; ignored by the `object` form."
 87    idempotency_key: str | None
 88    "Client-supplied deduplication key for this patch. A retry with the same key and the same ops replays the stored result without re-applying the write (survives server restarts); reusing a key with different ops returns 409."
 89    object: str | None
 90    "Custom object ID (`cobj_...`) to patch. Exactly one of `object` or `schema` + `row_key` is required."
 91    ops: Required[list[dict[str, Any]]]
 92    'Numeric patch ops to apply in order (e.g. `[%{"op" => "increment", "path" => "count", "by" => 1}]`). Supported ops: `increment` (`by`), `max`/`min` (`value`), `set_if_newer` (`value`, `fence_path`, `fence`).'
 93    row_key: str | None
 94    "Row key naming the row within `schema` (e.g. a counter name). Requires `schema`."
 95    schema: str | None
 96    "Schema type identifier (`lookup_key`) for the keyed form. Requires `row_key`."
 97    sort_key: list[str] | None
 98    "Sort-key segments partitioning rows within the `row_key` bucket. Only meaningful for schemas that declare a `sort_key`."
 99    team: str | None
100    "Team ID (`tem_...`) owning the keyed row. Defaults to the viewer's owner like the create contract."
101    user: str | None
102    "User ID (`usr_...`) owning the keyed row. At most one owner selector may be present."
103
104
105class CustomObjectReplaceInputAclAddItem(TypedDict, total=False):
106    actions: Required[list[str]]
107    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
108    principal: str | None
109    '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"`.'
110    principal_type: Required[str]
111    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
112
113
114class CustomObjectReplaceInputAclGrantsItem(TypedDict, total=False):
115    actions: Required[list[str]]
116    'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.'
117    principal: str | None
118    '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"`.'
119    principal_type: Required[str]
120    'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
121
122
123class CustomObjectReplaceInputAclRemoveItem(TypedDict, total=False):
124    principal: str | None
125    '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"`.'
126    principal_type: Required[str]
127    'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
128
129
130class CustomObjectReplaceInputAcl(TypedDict, total=False):
131    add: list[CustomObjectReplaceInputAclAddItem] | None
132    "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`."
133    grants: list[CustomObjectReplaceInputAclGrantsItem] | None
134    "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`."
135    remove: list[CustomObjectReplaceInputAclRemoveItem] | None
136    "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
137
138
139class CustomObjectReplaceInput(TypedDict, total=False):
140    "Update a custom object"
141
142    acl: CustomObjectReplaceInputAcl | None
143    "Updated access control list. Supports full replacement via `grants` or targeted `add`/`remove` operations."
144    expected_version: int | None
145    "Version number the caller expects to be current. If the object's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking and keep the existing OCC merge retry."
146    expires_at: datetime | None
147    "Absolute expiry time in RFC 3339 format. Pass null to clear; omit to leave unchanged on update."
148    field_ops: dict[str, Any] | None
149    "Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both `fields` and `field_ops`."
150    fields: dict[str, Any] | None
151    "Key-value map of field values to merge into the object. Only the supplied keys are affected."
152    idempotency_key: str | None
153    "Client-supplied deduplication key for this write. A retry with the same key and the same body replays the stored result without re-applying the write (survives server restarts); reusing a key with a different body returns 409."
154    type: str | None
155    "Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only."
156
157
158class CustomObjectPatchResponseDataAclAddItem(BaseModel):
159    actions: list[str] = Field(
160        ...,
161        description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.',
162    )
163    principal: str | None = Field(
164        default=None,
165        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"`.',
166    )
167    principal_type: str = Field(
168        ...,
169        description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
170    )
171
172
173class CustomObjectPatchResponseDataAclGrantsItem(BaseModel):
174    actions: list[str] = Field(
175        ...,
176        description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.',
177    )
178    principal: str | None = Field(
179        default=None,
180        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"`.',
181    )
182    principal_type: str = Field(
183        ...,
184        description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
185    )
186
187
188class CustomObjectPatchResponseDataAclRemoveItem(BaseModel):
189    principal: str | None = Field(
190        default=None,
191        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"`.',
192    )
193    principal_type: str = Field(
194        ...,
195        description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
196    )
197
198
199class CustomObjectPatchResponseDataAcl(BaseModel):
200    add: list[CustomObjectPatchResponseDataAclAddItem] | None = Field(
201        default=None,
202        description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.",
203    )
204    grants: list[CustomObjectPatchResponseDataAclGrantsItem] | None = Field(
205        default=None,
206        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`.",
207    )
208    remove: list[CustomObjectPatchResponseDataAclRemoveItem] | None = Field(
209        default=None,
210        description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.",
211    )
212
213
214class CustomObjectPatchResponseData(BaseModel):
215    acl: CustomObjectPatchResponseDataAcl | None = Field(
216        default=None,
217        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.",
218    )
219    agent: str | None = Field(
220        default=None,
221        description="ID of the agent that owns this object (`agt_...`). `null` for other ownership types.",
222    )
223    created_at: datetime | None = Field(
224        default=None, description="When the custom object was created (ISO 8601)."
225    )
226    expires_at: datetime | None = Field(
227        default=None, description="Absolute expiry time (RFC 3339). Null when no expiry is set."
228    )
229    fields: dict[str, Any] | None = Field(
230        default=None,
231        description="Map of field names to their current values as defined by the object's schema type.",
232    )
233    id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).")
234    org: str | None = Field(
235        default=None, description="ID of the organization this object belongs to (`org_...`)."
236    )
237    row_key: str | None = Field(
238        default=None,
239        description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.",
240    )
241    sandbox: str | None = Field(
242        default=None,
243        description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.",
244    )
245    schema_type: str | None = Field(
246        default=None,
247        description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.",
248    )
249    team: str | None = Field(
250        default=None,
251        description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.",
252    )
253    updated_at: datetime | None = Field(
254        default=None,
255        description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.",
256    )
257    user: str | None = Field(
258        default=None,
259        description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.",
260    )
261    version: int | None = Field(
262        default=None,
263        description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.",
264    )
265
266
267class CustomObjectPatchResponse(BaseModel):
268    """
269    Successful response
270    """
271
272    data: CustomObjectPatchResponseData = Field(
273        ..., description="The custom object after the patch has been applied."
274    )
275    meta: dict[str, Any] | None = Field(
276        default=None, description="Version metadata and per-op patch results."
277    )
278
279
280class CustomObjectDeleteResponse(BaseModel):
281    """
282    Successful response
283    """
284
285    deleted: bool = Field(..., description="Always `true` when the deletion succeeds.")
286    id: str = Field(..., description="ID of the deleted custom object (`cobj_...`).")
287
288
289class CustomObjectReplaceResponseDataAclAddItem(BaseModel):
290    actions: list[str] = Field(
291        ...,
292        description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.',
293    )
294    principal: str | None = Field(
295        default=None,
296        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"`.',
297    )
298    principal_type: str = Field(
299        ...,
300        description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
301    )
302
303
304class CustomObjectReplaceResponseDataAclGrantsItem(BaseModel):
305    actions: list[str] = Field(
306        ...,
307        description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.',
308    )
309    principal: str | None = Field(
310        default=None,
311        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"`.',
312    )
313    principal_type: str = Field(
314        ...,
315        description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
316    )
317
318
319class CustomObjectReplaceResponseDataAclRemoveItem(BaseModel):
320    principal: str | None = Field(
321        default=None,
322        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"`.',
323    )
324    principal_type: str = Field(
325        ...,
326        description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.',
327    )
328
329
330class CustomObjectReplaceResponseDataAcl(BaseModel):
331    add: list[CustomObjectReplaceResponseDataAclAddItem] | None = Field(
332        default=None,
333        description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.",
334    )
335    grants: list[CustomObjectReplaceResponseDataAclGrantsItem] | None = Field(
336        default=None,
337        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`.",
338    )
339    remove: list[CustomObjectReplaceResponseDataAclRemoveItem] | None = Field(
340        default=None,
341        description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.",
342    )
343
344
345class CustomObjectReplaceResponseData(BaseModel):
346    acl: CustomObjectReplaceResponseDataAcl | None = Field(
347        default=None,
348        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.",
349    )
350    agent: str | None = Field(
351        default=None,
352        description="ID of the agent that owns this object (`agt_...`). `null` for other ownership types.",
353    )
354    created_at: datetime | None = Field(
355        default=None, description="When the custom object was created (ISO 8601)."
356    )
357    expires_at: datetime | None = Field(
358        default=None, description="Absolute expiry time (RFC 3339). Null when no expiry is set."
359    )
360    fields: dict[str, Any] | None = Field(
361        default=None,
362        description="Map of field names to their current values as defined by the object's schema type.",
363    )
364    id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).")
365    org: str | None = Field(
366        default=None, description="ID of the organization this object belongs to (`org_...`)."
367    )
368    row_key: str | None = Field(
369        default=None,
370        description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.",
371    )
372    sandbox: str | None = Field(
373        default=None,
374        description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.",
375    )
376    schema_type: str | None = Field(
377        default=None,
378        description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.",
379    )
380    team: str | None = Field(
381        default=None,
382        description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.",
383    )
384    updated_at: datetime | None = Field(
385        default=None,
386        description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.",
387    )
388    user: str | None = Field(
389        default=None,
390        description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.",
391    )
392    version: int | None = Field(
393        default=None,
394        description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.",
395    )
396
397
398class CustomObjectReplaceResponse(BaseModel):
399    """
400    Successful response
401    """
402
403    data: CustomObjectReplaceResponseData = Field(
404        ..., description="The custom object after the update has been applied."
405    )
406    meta: dict[str, Any] | None = Field(
407        default=None, description="Version metadata for the updated object."
408    )
409
410
411class AsyncCustomObjectResource:
412    def __init__(self, http: HttpClient):
413        self._http = http
414
415    async def list(
416        self,
417        *,
418        type: str | None = None,
419        schema_key: str | None = None,
420        field_filters: dict[str, Any] | None = None,
421        system_only: bool | None = None,
422        order_by_field: str | None = None,
423        row_key: str | None = None,
424        sort_key: builtins.list[str] | None = None,
425        keys: builtins.list[dict[str, Any]] | None = None,
426        team: builtins.list[str] | None = None,
427        user: builtins.list[str] | None = None,
428        agent: builtins.list[str] | None = None,
429        org: builtins.list[str] | None = None,
430        query: str | None = None,
431        search: str | None = None,
432        page: int | None = None,
433        updated_since: datetime | None = None,
434        page_size: int | None = None,
435        include_count: bool | None = None,
436    ) -> CustomObjectListResponse:
437        """
438        List custom objects
439        Returns a paginated list of custom objects visible to the authenticated
440        viewer, ordered by creation time descending. Results span all ownership
441        types (team-owned, user-owned, agent-owned, and system-owned) that the
442        viewer has access to.
443        Filter by schema type with `type` (preferred) or the legacy alias
444        `schema_key`. Use the `row_key` param to perform an exact-match partition
445        lookup. You may additionally supply `sort_key` to narrow within that
446        partition `sort_key` requires `row_key` and the request returns 400 if
447        `sort_key` is provided alone. Owner filters (`team`, `user`, `agent`,
448        `org`) are additive: each accepts an array of IDs (or a single ID, which
449        is wrapped) and returns objects matching any of the supplied values.
450        When `query` is supplied, results are ranked by full-text relevance
451        (descending `ts_rank`) rather than creation time. The legacy `search`
452        param performs a case-insensitive substring match and is retained for
453        developer-namespace clients.
454
455        Args:
456            type: Schema type identifier (`lookup_key`) to filter by. Only objects of this type are returned. Alias of `schema_key`; either name is accepted.
457            schema_key: Legacy alias for `type`. Prefer `type` on new clients. When both are supplied, `type` wins.
458            field_filters: JSON containment predicates on fields, applied before pagination and counting.
459            system_only: Only system-owned objects (no user, team, agent or thread owner). Visibility is unchanged.
460            order_by_field: Top-level JSON field for descending text order, with ID tie-breaker. Full-text relevance takes precedence.
461            row_key: Exact `row_key` value to match. When supplied, only objects with this partition key are returned.
462            sort_key: One or more `sort_key` values to match within the `row_key` partition. Requires `row_key` to be set.
463            keys: JSON-encoded array of up to 100 objects with required string row_key and optional string-array sort_key. Missing or empty sort_key selects the whole partition. Mutually exclusive with row_key and sort_key. Pagination applies globally across all matched partitions.
464            team: One or more team IDs (`team_...`) to filter by owning team. Returns objects owned by any of the supplied teams.
465            user: One or more user IDs (`user_...`) to filter by owning user. Returns objects owned by any of the supplied users.
466            agent: One or more agent IDs to filter by owning agent. Returns objects owned by any of the supplied agents.
467            org: One or more organization IDs (`org_...`) to filter by. Typically used by admins to query system-owned objects in a specific org.
468            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.
469            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.
470            page: Page number to retrieve (1-indexed). Defaults to `1`.
471            updated_since: Include only objects updated at or after this ISO 8601 timestamp. Applies before pagination and counting.
472            page_size: Number of objects per page. Defaults to `25`; maximum is `100`.
473            include_count: Include total_entries and total_pages (default true). When false, totals are null, has_next uses one extra row, and pages beyond the end return an empty list without clamping. The page offset must fit PostgreSQL's signed 64-bit integer range.
474
475        Returns:
476            Paginated list of custom objects matching the supplied filters.
477        """
478        query: dict[str, object] = {}
479        if type is not None:
480            query["type"] = type
481        if schema_key is not None:
482            query["schema_key"] = schema_key
483        if field_filters is not None:
484            query["field_filters"] = field_filters
485        if system_only is not None:
486            query["system_only"] = system_only
487        if order_by_field is not None:
488            query["order_by_field"] = order_by_field
489        if row_key is not None:
490            query["row_key"] = row_key
491        if sort_key is not None:
492            query["sort_key"] = sort_key
493        if keys is not None:
494            query["keys"] = keys
495        if team is not None:
496            query["team"] = team
497        if user is not None:
498            query["user"] = user
499        if agent is not None:
500            query["agent"] = agent
501        if org is not None:
502            query["org"] = org
503        if query is not None:
504            query["query"] = query
505        if search is not None:
506            query["search"] = search
507        if page is not None:
508            query["page"] = page
509        if updated_since is not None:
510            query["updated_since"] = updated_since
511        if page_size is not None:
512            query["page_size"] = page_size
513        if include_count is not None:
514            query["include_count"] = include_count
515        return await self._http.request(
516            "/api/v1/custom_objects",
517            query=query,
518            response_type=CustomObjectListResponse,
519        )
520
521    async def create(self, input: CustomObjectCreateInput) -> CustomObject:
522        """
523        Create a custom object
524        Creates a new custom object of the given schema type and returns the
525        persisted object. The caller must be authenticated and authorized to create
526        objects of the specified type.
527        Identify the schema with `type` (preferred), or the legacy aliases
528        `schema_key` (lookup key) / `config` (config ID). Exactly one identifier is
529        required; when more than one is supplied, `type` wins over `schema_key`,
530        which wins over `config`.
531        Owner resolution follows a priority order: if `team` is supplied the object
532        is team-owned; if `user` is supplied it is owned by that user; if `agent` is
533        supplied it is agent-owned; otherwise the object is owned by the authenticated
534        user. Pass `system: true` explicitly to force system ownership this requires
535        elevated API credentials and returns 403 if the caller lacks permission.
536        If the schema declares a `row_key` (and optionally a `sort_key`), you may
537        pass `upsert: true` to update an existing object at that key instead of
538        receiving a 409 Conflict. The response status is `200` on an update and
539        `201` on a new create.
540
541        Args:
542            input: Request body.
543            input.acl: Access control list for the custom object. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.
544            input.agent: Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied.
545            input.config: Config ID (`cfg_...`) that resolves to the target schema. Provide one of `type`, `schema_key`, or `config`.
546            input.expires_at: Absolute expiry time in RFC 3339 format. Pass null to clear; omit to leave unchanged on update.
547            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.
548            input.org: Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects.
549            input.schema_key: Legacy alias for `type` (schema `lookup_key`). Prefer `type` on new clients. Provide one of `type`, `schema_key`, or `config`.
550            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.
551            input.team: Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`.
552            input.type: Schema type identifier (`lookup_key`) that defines the object's shape and validation rules. Preferred over the legacy `schema_key` / `config` aliases.
553            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.
554            input.user: User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set.
555
556        Returns:
557            The created (or upserted) custom object.
558        """
559        return await self._http.request(
560            "/api/v1/custom_objects",
561            method="POST",
562            body=input,
563            response_type=CustomObject,
564        )
565
566    async def patch(self, input: CustomObjectPatchInput) -> CustomObjectPatchResponse:
567        """
568        Apply numeric patch ops to a custom object
569        Applies numeric patch ops (`increment`, `max`, `min`, `set_if_newer` with
570        dotted `path`s) atomically to a custom object and returns the updated
571        object along with per-op results. The authenticated viewer must have
572        permission to modify the object.
573        Address the row in one of two ways: by `object` ID (`cobj_...`), or by
574        `schema` + `row_key` (with optional `sort_key` for schemas that declare
575        one). The keyed form resolves the row for the same owner the create
576        contract would use and, when no row exists yet, creates it from
577        `create_with` merged over the key fields before applying the ops so an
578        aggregator's first call creates the counter and later calls increment it.
579        A racing create resolves to the same row instead of a duplicate.
580        Pass `idempotency_key` to make retries safe: a retry with the same key and
581        ops replays the stored result without re-applying the write (survives
582        server restarts); reusing a key with different ops returns 409.
583
584        Args:
585            input: Request body.
586            input.agent: Agent user ID owning the keyed row. At most one owner selector may be present.
587            input.create_with: Field values used to create the row when the keyed form finds no existing row. Merged over the key fields before validation; ignored by the `object` form.
588            input.idempotency_key: Client-supplied deduplication key for this patch. A retry with the same key and the same ops replays the stored result without re-applying the write (survives server restarts); reusing a key with different ops returns 409.
589            input.object: Custom object ID (`cobj_...`) to patch. Exactly one of `object` or `schema` + `row_key` is required.
590            input.ops: Numeric patch ops to apply in order (e.g. `[%{"op" => "increment", "path" => "count", "by" => 1}]`). Supported ops: `increment` (`by`), `max`/`min` (`value`), `set_if_newer` (`value`, `fence_path`, `fence`).
591            input.row_key: Row key naming the row within `schema` (e.g. a counter name). Requires `schema`.
592            input.schema: Schema type identifier (`lookup_key`) for the keyed form. Requires `row_key`.
593            input.sort_key: Sort-key segments partitioning rows within the `row_key` bucket. Only meaningful for schemas that declare a `sort_key`.
594            input.team: Team ID (`tem_...`) owning the keyed row. Defaults to the viewer's owner like the create contract.
595            input.user: User ID (`usr_...`) owning the keyed row. At most one owner selector may be present.
596
597        Returns:
598            Successful response
599        """
600        return await self._http.request(
601            "/api/v1/custom_objects/patch",
602            method="POST",
603            body=input,
604            response_type=CustomObjectPatchResponse,
605        )
606
607    async def delete(self, object: str) -> CustomObjectDeleteResponse:
608        """
609        Delete a custom object
610        Permanently deletes the custom object identified by `object`. The caller
611        must be authenticated and have permission to delete the object.
612        On success, returns a confirmation payload containing the deleted object's
613        ID so callers can confirm the deletion without a follow-up fetch.
614        Attempting to delete an object that does not exist or has already been
615        deleted returns 404.
616
617        Args:
618            object: Custom object ID (`cobj_...`) of the object to delete.
619
620        Returns:
621            Successful response
622        """
623        return await self._http.request(
624            f"/api/v1/custom_objects/{object}",
625            method="DELETE",
626            response_type=CustomObjectDeleteResponse,
627        )
628
629    async def get(self, object: str, *, type: str | None = None) -> CustomObject:
630        """
631        Retrieve a custom object
632        Returns a single custom object identified by its ID. The authenticated viewer
633        must have visibility access to the object.
634        Returns 404 if the object does not exist, has been deleted, or is not
635        visible to the viewer.
636
637        Args:
638            object: Custom object ID (`cobj_...`) to retrieve.
639            type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
640
641        Returns:
642            The requested custom object.
643        """
644        query: dict[str, object] = {}
645        if type is not None:
646            query["type"] = type
647        return await self._http.request(
648            f"/api/v1/custom_objects/{object}",
649            query=query,
650            response_type=CustomObject,
651        )
652
653    async def replace(
654        self, object: str, input: CustomObjectReplaceInput
655    ) -> CustomObjectReplaceResponse:
656        """
657        Update a custom object
658        Updates the fields of an existing custom object and returns the updated
659        object along with its new version number. The authenticated viewer must have
660        permission to modify the object.
661        You may supply `fields` (a full or partial key-value map to merge into the
662        object), `field_ops` (granular array operations per field), `acl`, or any
663        compatible combination. The same field name must not appear in both
664        `fields` and `field_ops`, which returns 422. Returns 404 if the object does
665        not exist or has been deleted.
666        Use `expected_version` for optimistic concurrency: if the object's current
667        `aggregate_version` does not match, the request returns 409 and does not
668        retry the caller write. Omit it to keep the existing OCC merge retry.
669
670        Args:
671            object: Custom object ID (`cobj_...`) to update.
672            input: Request body.
673            input.acl: Updated access control list. Supports full replacement via `grants` or targeted `add`/`remove` operations.
674            input.expected_version: Version number the caller expects to be current. If the object's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking and keep the existing OCC merge retry.
675            input.expires_at: Absolute expiry time in RFC 3339 format. Pass null to clear; omit to leave unchanged on update.
676            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`.
677            input.fields: Key-value map of field values to merge into the object. Only the supplied keys are affected.
678            input.idempotency_key: Client-supplied deduplication key for this write. A retry with the same key and the same body replays the stored result without re-applying the write (survives server restarts); reusing a key with a different body returns 409.
679            input.type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
680
681        Returns:
682            Successful response
683        """
684        return await self._http.request(
685            f"/api/v1/custom_objects/{object}",
686            method="PUT",
687            body=input,
688            response_type=CustomObjectReplaceResponse,
689        )
690
691
692class CustomObjectResource:
693    def __init__(self, http: SyncHttpClient):
694        self._http = http
695
696    def list(
697        self,
698        *,
699        type: str | None = None,
700        schema_key: str | None = None,
701        field_filters: dict[str, Any] | None = None,
702        system_only: bool | None = None,
703        order_by_field: str | None = None,
704        row_key: str | None = None,
705        sort_key: builtins.list[str] | None = None,
706        keys: builtins.list[dict[str, Any]] | None = None,
707        team: builtins.list[str] | None = None,
708        user: builtins.list[str] | None = None,
709        agent: builtins.list[str] | None = None,
710        org: builtins.list[str] | None = None,
711        query: str | None = None,
712        search: str | None = None,
713        page: int | None = None,
714        updated_since: datetime | None = None,
715        page_size: int | None = None,
716        include_count: bool | None = None,
717    ) -> CustomObjectListResponse:
718        """
719        List custom objects
720        Returns a paginated list of custom objects visible to the authenticated
721        viewer, ordered by creation time descending. Results span all ownership
722        types (team-owned, user-owned, agent-owned, and system-owned) that the
723        viewer has access to.
724        Filter by schema type with `type` (preferred) or the legacy alias
725        `schema_key`. Use the `row_key` param to perform an exact-match partition
726        lookup. You may additionally supply `sort_key` to narrow within that
727        partition `sort_key` requires `row_key` and the request returns 400 if
728        `sort_key` is provided alone. Owner filters (`team`, `user`, `agent`,
729        `org`) are additive: each accepts an array of IDs (or a single ID, which
730        is wrapped) and returns objects matching any of the supplied values.
731        When `query` is supplied, results are ranked by full-text relevance
732        (descending `ts_rank`) rather than creation time. The legacy `search`
733        param performs a case-insensitive substring match and is retained for
734        developer-namespace clients.
735
736        Args:
737            type: Schema type identifier (`lookup_key`) to filter by. Only objects of this type are returned. Alias of `schema_key`; either name is accepted.
738            schema_key: Legacy alias for `type`. Prefer `type` on new clients. When both are supplied, `type` wins.
739            field_filters: JSON containment predicates on fields, applied before pagination and counting.
740            system_only: Only system-owned objects (no user, team, agent or thread owner). Visibility is unchanged.
741            order_by_field: Top-level JSON field for descending text order, with ID tie-breaker. Full-text relevance takes precedence.
742            row_key: Exact `row_key` value to match. When supplied, only objects with this partition key are returned.
743            sort_key: One or more `sort_key` values to match within the `row_key` partition. Requires `row_key` to be set.
744            keys: JSON-encoded array of up to 100 objects with required string row_key and optional string-array sort_key. Missing or empty sort_key selects the whole partition. Mutually exclusive with row_key and sort_key. Pagination applies globally across all matched partitions.
745            team: One or more team IDs (`team_...`) to filter by owning team. Returns objects owned by any of the supplied teams.
746            user: One or more user IDs (`user_...`) to filter by owning user. Returns objects owned by any of the supplied users.
747            agent: One or more agent IDs to filter by owning agent. Returns objects owned by any of the supplied agents.
748            org: One or more organization IDs (`org_...`) to filter by. Typically used by admins to query system-owned objects in a specific org.
749            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.
750            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.
751            page: Page number to retrieve (1-indexed). Defaults to `1`.
752            updated_since: Include only objects updated at or after this ISO 8601 timestamp. Applies before pagination and counting.
753            page_size: Number of objects per page. Defaults to `25`; maximum is `100`.
754            include_count: Include total_entries and total_pages (default true). When false, totals are null, has_next uses one extra row, and pages beyond the end return an empty list without clamping. The page offset must fit PostgreSQL's signed 64-bit integer range.
755
756        Returns:
757            Paginated list of custom objects matching the supplied filters.
758        """
759        query: dict[str, object] = {}
760        if type is not None:
761            query["type"] = type
762        if schema_key is not None:
763            query["schema_key"] = schema_key
764        if field_filters is not None:
765            query["field_filters"] = field_filters
766        if system_only is not None:
767            query["system_only"] = system_only
768        if order_by_field is not None:
769            query["order_by_field"] = order_by_field
770        if row_key is not None:
771            query["row_key"] = row_key
772        if sort_key is not None:
773            query["sort_key"] = sort_key
774        if keys is not None:
775            query["keys"] = keys
776        if team is not None:
777            query["team"] = team
778        if user is not None:
779            query["user"] = user
780        if agent is not None:
781            query["agent"] = agent
782        if org is not None:
783            query["org"] = org
784        if query is not None:
785            query["query"] = query
786        if search is not None:
787            query["search"] = search
788        if page is not None:
789            query["page"] = page
790        if updated_since is not None:
791            query["updated_since"] = updated_since
792        if page_size is not None:
793            query["page_size"] = page_size
794        if include_count is not None:
795            query["include_count"] = include_count
796        return self._http.request(
797            "/api/v1/custom_objects",
798            query=query,
799            response_type=CustomObjectListResponse,
800        )
801
802    def create(self, input: CustomObjectCreateInput) -> CustomObject:
803        """
804        Create a custom object
805        Creates a new custom object of the given schema type and returns the
806        persisted object. The caller must be authenticated and authorized to create
807        objects of the specified type.
808        Identify the schema with `type` (preferred), or the legacy aliases
809        `schema_key` (lookup key) / `config` (config ID). Exactly one identifier is
810        required; when more than one is supplied, `type` wins over `schema_key`,
811        which wins over `config`.
812        Owner resolution follows a priority order: if `team` is supplied the object
813        is team-owned; if `user` is supplied it is owned by that user; if `agent` is
814        supplied it is agent-owned; otherwise the object is owned by the authenticated
815        user. Pass `system: true` explicitly to force system ownership this requires
816        elevated API credentials and returns 403 if the caller lacks permission.
817        If the schema declares a `row_key` (and optionally a `sort_key`), you may
818        pass `upsert: true` to update an existing object at that key instead of
819        receiving a 409 Conflict. The response status is `200` on an update and
820        `201` on a new create.
821
822        Args:
823            input: Request body.
824            input.acl: Access control list for the custom object. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.
825            input.agent: Agent user ID to set as the object owner. Used when neither `team` nor `user` is supplied.
826            input.config: Config ID (`cfg_...`) that resolves to the target schema. Provide one of `type`, `schema_key`, or `config`.
827            input.expires_at: Absolute expiry time in RFC 3339 format. Pass null to clear; omit to leave unchanged on update.
828            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.
829            input.org: Organization ID (`org_...`) to associate with the object. Typically required for system-owned objects.
830            input.schema_key: Legacy alias for `type` (schema `lookup_key`). Prefer `type` on new clients. Provide one of `type`, `schema_key`, or `config`.
831            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.
832            input.team: Team ID (`team_...`) to set as the object owner. When supplied, takes priority over `user` and `agent`.
833            input.type: Schema type identifier (`lookup_key`) that defines the object's shape and validation rules. Preferred over the legacy `schema_key` / `config` aliases.
834            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.
835            input.user: User ID (`user_...`) to set as the object owner. Used when neither `team` nor a higher-priority owner is set.
836
837        Returns:
838            The created (or upserted) custom object.
839        """
840        return self._http.request(
841            "/api/v1/custom_objects",
842            method="POST",
843            body=input,
844            response_type=CustomObject,
845        )
846
847    def patch(self, input: CustomObjectPatchInput) -> CustomObjectPatchResponse:
848        """
849        Apply numeric patch ops to a custom object
850        Applies numeric patch ops (`increment`, `max`, `min`, `set_if_newer` with
851        dotted `path`s) atomically to a custom object and returns the updated
852        object along with per-op results. The authenticated viewer must have
853        permission to modify the object.
854        Address the row in one of two ways: by `object` ID (`cobj_...`), or by
855        `schema` + `row_key` (with optional `sort_key` for schemas that declare
856        one). The keyed form resolves the row for the same owner the create
857        contract would use and, when no row exists yet, creates it from
858        `create_with` merged over the key fields before applying the ops so an
859        aggregator's first call creates the counter and later calls increment it.
860        A racing create resolves to the same row instead of a duplicate.
861        Pass `idempotency_key` to make retries safe: a retry with the same key and
862        ops replays the stored result without re-applying the write (survives
863        server restarts); reusing a key with different ops returns 409.
864
865        Args:
866            input: Request body.
867            input.agent: Agent user ID owning the keyed row. At most one owner selector may be present.
868            input.create_with: Field values used to create the row when the keyed form finds no existing row. Merged over the key fields before validation; ignored by the `object` form.
869            input.idempotency_key: Client-supplied deduplication key for this patch. A retry with the same key and the same ops replays the stored result without re-applying the write (survives server restarts); reusing a key with different ops returns 409.
870            input.object: Custom object ID (`cobj_...`) to patch. Exactly one of `object` or `schema` + `row_key` is required.
871            input.ops: Numeric patch ops to apply in order (e.g. `[%{"op" => "increment", "path" => "count", "by" => 1}]`). Supported ops: `increment` (`by`), `max`/`min` (`value`), `set_if_newer` (`value`, `fence_path`, `fence`).
872            input.row_key: Row key naming the row within `schema` (e.g. a counter name). Requires `schema`.
873            input.schema: Schema type identifier (`lookup_key`) for the keyed form. Requires `row_key`.
874            input.sort_key: Sort-key segments partitioning rows within the `row_key` bucket. Only meaningful for schemas that declare a `sort_key`.
875            input.team: Team ID (`tem_...`) owning the keyed row. Defaults to the viewer's owner like the create contract.
876            input.user: User ID (`usr_...`) owning the keyed row. At most one owner selector may be present.
877
878        Returns:
879            Successful response
880        """
881        return self._http.request(
882            "/api/v1/custom_objects/patch",
883            method="POST",
884            body=input,
885            response_type=CustomObjectPatchResponse,
886        )
887
888    def delete(self, object: str) -> CustomObjectDeleteResponse:
889        """
890        Delete a custom object
891        Permanently deletes the custom object identified by `object`. The caller
892        must be authenticated and have permission to delete the object.
893        On success, returns a confirmation payload containing the deleted object's
894        ID so callers can confirm the deletion without a follow-up fetch.
895        Attempting to delete an object that does not exist or has already been
896        deleted returns 404.
897
898        Args:
899            object: Custom object ID (`cobj_...`) of the object to delete.
900
901        Returns:
902            Successful response
903        """
904        return self._http.request(
905            f"/api/v1/custom_objects/{object}",
906            method="DELETE",
907            response_type=CustomObjectDeleteResponse,
908        )
909
910    def get(self, object: str, *, type: str | None = None) -> CustomObject:
911        """
912        Retrieve a custom object
913        Returns a single custom object identified by its ID. The authenticated viewer
914        must have visibility access to the object.
915        Returns 404 if the object does not exist, has been deleted, or is not
916        visible to the viewer.
917
918        Args:
919            object: Custom object ID (`cobj_...`) to retrieve.
920            type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
921
922        Returns:
923            The requested custom object.
924        """
925        query: dict[str, object] = {}
926        if type is not None:
927            query["type"] = type
928        return self._http.request(
929            f"/api/v1/custom_objects/{object}",
930            query=query,
931            response_type=CustomObject,
932        )
933
934    def replace(self, object: str, input: CustomObjectReplaceInput) -> CustomObjectReplaceResponse:
935        """
936        Update a custom object
937        Updates the fields of an existing custom object and returns the updated
938        object along with its new version number. The authenticated viewer must have
939        permission to modify the object.
940        You may supply `fields` (a full or partial key-value map to merge into the
941        object), `field_ops` (granular array operations per field), `acl`, or any
942        compatible combination. The same field name must not appear in both
943        `fields` and `field_ops`, which returns 422. Returns 404 if the object does
944        not exist or has been deleted.
945        Use `expected_version` for optimistic concurrency: if the object's current
946        `aggregate_version` does not match, the request returns 409 and does not
947        retry the caller write. Omit it to keep the existing OCC merge retry.
948
949        Args:
950            object: Custom object ID (`cobj_...`) to update.
951            input: Request body.
952            input.acl: Updated access control list. Supports full replacement via `grants` or targeted `add`/`remove` operations.
953            input.expected_version: Version number the caller expects to be current. If the object's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking and keep the existing OCC merge retry.
954            input.expires_at: Absolute expiry time in RFC 3339 format. Pass null to clear; omit to leave unchanged on update.
955            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`.
956            input.fields: Key-value map of field values to merge into the object. Only the supplied keys are affected.
957            input.idempotency_key: Client-supplied deduplication key for this write. A retry with the same key and the same body replays the stored result without re-applying the write (survives server restarts); reusing a key with a different body returns 409.
958            input.type: Schema type identifier (`lookup_key`) of the object. Optional; used for routing context only.
959
960        Returns:
961            Successful response
962        """
963        return self._http.request(
964            f"/api/v1/custom_objects/{object}",
965            method="PUT",
966            body=input,
967            response_type=CustomObjectReplaceResponse,
968        )