@archastro/sdk
    Preparing search index...

    Class CustomObjectResource

    Index

    Constructors

    constructor

    Methods

    create delete get list replace

    Constructors

    Methods

    • Create a custom object Creates a new custom object of the given schema type and returns the persisted object. The caller must be authenticated and authorized to create objects of the specified type. Identify the schema with type (preferred), or the legacy aliases schema_key (lookup key) / config (config ID). Exactly one identifier is required; when more than one is supplied, type wins over schema_key, which wins over config. Owner resolution follows a priority order: if team is supplied the object is team-owned; if user is supplied it is owned by that user; if agent is supplied it is agent-owned; otherwise the object is owned by the authenticated user. Pass system: true explicitly to force system ownership — this requires elevated API credentials and returns 403 if the caller lacks permission. If the schema declares a row_key (and optionally a sort_key), you may pass upsert: true to update an existing object at that key instead of receiving a 409 Conflict. The response status is 200 on an update and 201 on a new create.

      Parameters

      • input: {
            acl?: {
                add?: { actions: string[]; principal?: string; principal_type: string }[];
                grants?: { actions: string[]; principal?: string; principal_type: string }[];
                remove?: { principal?: string; principal_type: string }[];
            };
            agent?: string;
            config?: string;
            fields?: Record<string, unknown>;
            org?: string;
            schema_key?: string;
            system?: boolean;
            team?: string;
            type?: string;
            upsert?: boolean;
            user?: string;
        }

        Request body.

        • Optionalacl?: {
              add?: { actions: string[]; principal?: string; principal_type: string }[];
              grants?: { actions: string[]; principal?: string; principal_type: string }[];
              remove?: { principal?: string; principal_type: string }[];
          }

          Access control list for the custom object. Supports explicit read and write grants to users, teams, organizations, organization roles, agents, or everyone.

        • Optionalagent?: string

          Agent user ID to set as the object owner. Used when neither team nor user is supplied.

        • Optionalconfig?: string

          Config ID (cfg_...) that resolves to the target schema. Provide one of type, schema_key, or config.

        • Optionalfields?: Record<string, unknown>

          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.

        • Optionalorg?: string

          Organization ID (org_...) to associate with the object. Typically required for system-owned objects.

        • Optionalschema_key?: string

          Legacy alias for type (schema lookup_key). Prefer type on new clients. Provide one of type, schema_key, or config.

        • Optionalsystem?: boolean

          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.

        • Optionalteam?: string

          Team ID (team_...) to set as the object owner. When supplied, takes priority over user and agent.

        • Optionaltype?: string

          Schema type identifier (lookup_key) that defines the object's shape and validation rules. Preferred over the legacy schema_key / config aliases.

        • Optionalupsert?: boolean

          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.

        • Optionaluser?: string

          User ID (user_...) to set as the object owner. Used when neither team nor a higher-priority owner is set.

      Returns Promise<CustomObject>

      The created (or upserted) custom object.

    • Delete a custom object Permanently deletes the custom object identified by object. The caller must be authenticated and have permission to delete the object. On success, returns a confirmation payload containing the deleted object's ID so callers can confirm the deletion without a follow-up fetch. Attempting to delete an object that does not exist or has already been deleted returns 404.

      Parameters

      • object: string

        Custom object ID (cobj_...) of the object to delete.

      Returns Promise<{ deleted: boolean; id: string }>

      Successful response

    • Retrieve a custom object Returns a single custom object identified by its ID. The authenticated viewer must have visibility access to the object. Returns 404 if the object does not exist, has been deleted, or is not visible to the viewer.

      Parameters

      • object: string

        Custom object ID (cobj_...) to retrieve.

      • Optionalparams: { type?: string }

        Query parameters.

        • Optionaltype?: string

          Schema type identifier (lookup_key) of the object. Optional; used for routing context only.

      Returns Promise<CustomObject>

      The requested custom object.

    • List custom objects Returns a paginated list of custom objects visible to the authenticated viewer, ordered by creation time descending. Results span all ownership types (team-owned, user-owned, agent-owned, and system-owned) that the viewer has access to. Filter by schema type with type (preferred) or the legacy alias schema_key. Use the row_key param to perform an exact-match partition lookup. You may additionally supply sort_key to narrow within that partition — sort_key requires row_key and the request returns 400 if sort_key is provided alone. Owner filters (team, user, agent, org) are additive: each accepts an array of IDs (or a single ID, which is wrapped) and returns objects matching any of the supplied values. When query is supplied, results are ranked by full-text relevance (descending ts_rank) rather than creation time. The legacy search param performs a case-insensitive substring match and is retained for developer-namespace clients.

      Parameters

      • Optionalparams: {
            agent?: string[];
            org?: string[];
            page?: number;
            pageSize?: number;
            query?: string;
            rowKey?: string;
            schemaKey?: string;
            search?: string;
            sortKey?: string[];
            team?: string[];
            type?: string;
            user?: string[];
        }

        Query parameters.

        • Optionalagent?: string[]

          One or more agent IDs to filter by owning agent. Returns objects owned by any of the supplied agents.

        • Optionalorg?: string[]

          One or more organization IDs (org_...) to filter by. Typically used by admins to query system-owned objects in a specific org.

        • Optionalpage?: number

          Page number to retrieve (1-indexed). Defaults to 1.

        • OptionalpageSize?: number

          Number of objects per page. Defaults to 25; maximum is 100.

        • Optionalquery?: string

          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.

        • OptionalrowKey?: string

          Exact row_key value to match. When supplied, only objects with this partition key are returned.

        • OptionalschemaKey?: string

          Legacy alias for type. Prefer type on new clients. When both are supplied, type wins.

        • Optionalsearch?: string

          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.

        • OptionalsortKey?: string[]

          One or more sort_key values to match within the row_key partition. Requires row_key to be set.

        • Optionalteam?: string[]

          One or more team IDs (team_...) to filter by owning team. Returns objects owned by any of the supplied teams.

        • Optionaltype?: string

          Schema type identifier (lookup_key) to filter by. Only objects of this type are returned. Alias of schema_key; either name is accepted.

        • Optionaluser?: string[]

          One or more user IDs (user_...) to filter by owning user. Returns objects owned by any of the supplied users.

      Returns Promise<CustomObjectListResponse>

      Paginated list of custom objects matching the supplied filters.

    • Update a custom object Updates the fields of an existing custom object and returns the updated object along with its new version number. The authenticated viewer must have permission to modify the object. You may supply fields (a full or partial key-value map to merge into the object), field_ops (granular array operations per field), acl, or any compatible combination. The same field name must not appear in both fields and field_ops, which returns 422. Returns 404 if the object does not exist or has been deleted.

      Parameters

      • object: string

        Custom object ID (cobj_...) to update.

      • input: {
            acl?: {
                add?: { actions: string[]; principal?: string; principal_type: string }[];
                grants?: { actions: string[]; principal?: string; principal_type: string }[];
                remove?: { principal?: string; principal_type: string }[];
            };
            field_ops?: Record<string, unknown>;
            fields?: Record<string, unknown>;
            type?: string;
        }

        Request body.

        • Optionalacl?: {
              add?: { actions: string[]; principal?: string; principal_type: string }[];
              grants?: { actions: string[]; principal?: string; principal_type: string }[];
              remove?: { principal?: string; principal_type: string }[];
          }

          Updated access control list. Supports full replacement via grants or targeted add/remove operations.

        • Optionalfield_ops?: Record<string, unknown>

          Granular array operations to apply per field (e.g. append, prepend, remove). A field must not appear in both fields and field_ops.

        • Optionalfields?: Record<string, unknown>

          Key-value map of field values to merge into the object. Only the supplied keys are affected.

        • Optionaltype?: string

          Schema type identifier (lookup_key) of the object. Optional; used for routing context only.

      Returns Promise<
          {
              data: {
                  acl?: {
                      add?: {
                          actions: string[];
                          principal?: string;
                          principal_type: string;
                      }[];
                      grants?: {
                          actions: string[];
                          principal?: string;
                          principal_type: string;
                      }[];
                      remove?: { principal?: string; principal_type: string }[];
                  };
                  created_at?: string;
                  fields?: Record<string, unknown>;
                  id: string;
                  org?: string;
                  row_key?: string;
                  sandbox?: string;
                  schema_type?: string;
                  team?: string;
                  updated_at?: string;
                  user?: string;
                  version?: number;
              };
              meta?: Record<string, unknown>;
          },
      >

      Successful response

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods