@archastro/sdk
    Preparing search index...

    Class UserTaskResource

    Index

    Constructors

    constructor

    Methods

    blockerCycles create list ready search

    Constructors

    Methods

    • List task blocker cycles Runs an on-demand diagnostic over unfinished tasks owned by the specified team or user and returns a forward cursor-paginated page of complete cyclic blocker components. Detection is bounded to owners with at most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent task updates, lease acquisition, or completion.

      Parameters

      • user: string

        User ID (usr_...) for user-scoped tasks.

      • Optionalparams: { afterCursor?: string; limit?: number; org?: string; team?: string }

        Query parameters.

        • OptionalafterCursor?: string

          Opaque cursor returned by the preceding page.

        • Optionallimit?: number

          Maximum cycle components to return. Defaults to 50; maximum is 100.

        • Optionalorg?: string

          Optional organization context for privileged callers.

        • Optionalteam?: string

          Team ID (tem_...) owning the tasks.

      Returns Promise<
          {
              after_cursor?: string;
              before_cursor?: string;
              data: {
                  tasks: {
                      agent?: string
                      | null;
                      aggregate_version?: number | null;
                      blocked_by_count?: number;
                      closed_at?: string | null;
                      comments_count?: number;
                      created_at?: string;
                      created_by_actor?:
                          | {
                              alias?: string
                              | null;
                              id?: string | null;
                              name?: string | null;
                              profile_picture?:
                                  | {
                                      file?: (...)
                                      | (...)
                                      | (...);
                                      height?: (...) | (...) | (...);
                                      media?: (...) | (...) | (...);
                                      mime_type?: (...) | (...) | (...);
                                      refresh_url?: (...) | (...) | (...);
                                      url?: (...) | (...) | (...);
                                      width?: (...) | (...) | (...);
                                  }
                                  | null;
                          }
                          | null;
                      created_by_agent?: string
                      | null;
                      created_by_user?: string | null;
                      current_lease?:
                          | { expires_at: string; harness: string; session_name: string }
                          | null;
                      description?: string | null;
                      due_date?: string | null;
                      epic?: string | null;
                      id: string;
                      is_blocked?: boolean;
                      links?: Record<string, unknown>;
                      metadata?: Record<string, unknown>;
                      name: string;
                      org?: string | null;
                      owner_actor?:
                          | {
                              alias?: string
                              | null;
                              id?: string | null;
                              name?: string | null;
                              profile_picture?:
                                  | {
                                      file?: (...)
                                      | (...)
                                      | (...);
                                      height?: (...) | (...) | (...);
                                      media?: (...) | (...) | (...);
                                      mime_type?: (...) | (...) | (...);
                                      refresh_url?: (...) | (...) | (...);
                                      url?: (...) | (...) | (...);
                                      width?: (...) | (...) | (...);
                                  }
                                  | null;
                          }
                          | null;
                      owner_agent?: string
                      | null;
                      owner_user?: string | null;
                      parent?: string | null;
                      priority?: number;
                      sandbox?: string | null;
                      source_id?: string | null;
                      source_scope?: string | null;
                      source_type?: string | null;
                      status: string;
                      subtasks_count?: number;
                      tags?: string[];
                      team?: string | null;
                      thread?: string | null;
                      updated_at?: string;
                      user?: string | null;
                  }[];
              }[];
              has_more: boolean;
          },
      >

      Successful response

    • Create a task for an owner Creates a new task owned by the specified user or team and returns the full task object. User-authenticated calls are attributed to the authenticated user or agent. App-scoped developer and server-to-server callers must provide the task's explicit org scope and an explicit user or agent actor for team tasks; a user-owned task reuses the user in the route unless an explicit agent is supplied. Every referenced principal is validated against the app, owner, and team membership before creation.

      Parameters

      • user: string

        User ID (usr_...) for user-scoped tasks.

      • input: {
            agent?: string;
            org?: string;
            task: {
                description?: string;
                due_date?: string;
                epic?: string;
                links?: Record<string, unknown>;
                metadata?: Record<string, unknown>;
                name: string;
                owner_agent?: string;
                owner_user?: string;
                parent?: string;
                priority?: number;
                source_id?: string;
                source_scope?: string;
                source_type?: string;
                status?: string;
                tags?: string[];
                thread?: string;
            };
            team?: string;
        }

        Request body.

        • Optionalagent?: string

          Explicit acting agent (agi_...) for a developer or server-to-server call. Mutually exclusive with an acting user; the agent must belong to the task owner.

        • Optionalorg?: string

          Explicit organization (org_...) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team.

        • task: {
              description?: string;
              due_date?: string;
              epic?: string;
              links?: Record<string, unknown>;
              metadata?: Record<string, unknown>;
              name: string;
              owner_agent?: string;
              owner_user?: string;
              parent?: string;
              priority?: number;
              source_id?: string;
              source_scope?: string;
              source_type?: string;
              status?: string;
              tags?: string[];
              thread?: string;
          }

          Attributes for the task to create. name is required; all other fields are optional.

        • Optionalteam?: string

          Team ID (tem_...). The task will be owned by this team.

      Returns Promise<Task>

      The newly created task.

    • List an owner's tasks Returns tasks owned by the specified user or team. You can narrow results using the optional filters below. By default results are returned in reverse chronological order (most recently created first); use sort and order to sort by due date or priority instead. User-authenticated callers may list their personal tasks or tasks for teams they have joined. Privileged callers provide the owner in the route; the owner's organization is implied by that principal. An explicit org is optional and, when set, must match the owner's organization.

      Parameters

      • user: string

        User ID (usr_...) for user-scoped tasks.

      • Optionalparams: {
            afterCursor?: string;
            dueAfter?: string;
            dueBefore?: string;
            epic?: string;
            limit?: number;
            order?: string;
            org?: string;
            overdue?: boolean;
            ownerAgent?: string;
            ownerUser?: string;
            parent?: string;
            priority?: number;
            ready?: boolean;
            search?: string;
            sort?: string;
            sourceId?: string;
            sourceScope?: string;
            sourceType?: string;
            status?: string;
            tag?: string;
            team?: string;
        }

        Query parameters.

        • OptionalafterCursor?: string

          Opaque cursor returned by the previous page.

        • OptionaldueAfter?: string

          Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded.

        • OptionaldueBefore?: string

          Return only tasks with a due date strictly before this ISO 8601 datetime (2026-08-01T00:00:00Z) or date (2026-08-01, meaning midnight UTC). Tasks without a due date are excluded.

        • Optionalepic?: string

          Return only tasks with this exact epic label.

        • Optionallimit?: number

          Maximum number of tasks to return. Capped at 100.

        • Optionalorder?: string

          Sort direction, "asc" or "desc". Defaults to "desc" for created and "asc" for due_date and priority.

        • Optionalorg?: string

          Optional organization (org_...) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization.

        • Optionaloverdue?: boolean

          When true, return only overdue tasks: a due date before the current UTC day and a status other than "done". A task due today is not overdue.

        • OptionalownerAgent?: string

          Filter tasks assigned to a specific agent. Provide the agent's public ID (agi_...).

        • OptionalownerUser?: string

          Filter tasks assigned to a specific user. Provide the user's public ID (usr_...).

        • Optionalparent?: string

          Return only subtasks of the given task (tsk_...), or pass none to return only top-level tasks.

        • Optionalpriority?: number

          Filter tasks by priority, from 0 (highest) to 4 (lowest).

        • Optionalready?: boolean

          When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work.

        • Optionalsearch?: string

          Restrict results to tasks whose name or description contains this string.

        • Optionalsort?: string

          Sort key. One of "created" (default — most recently created first), "due_date" (soonest due first; tasks without a due date always sort last), or "priority" (most urgent first). Ties break by most recently created.

        • OptionalsourceId?: string

          Return only tasks whose source matches this object identity. Must be supplied with the other source filters.

        • OptionalsourceScope?: string

          Return only tasks whose source matches this container. Must be supplied with source_type and source_id.

        • OptionalsourceType?: string

          Return only tasks whose source matches this object kind. Must be supplied with the other source filters.

        • Optionalstatus?: string

          Filter tasks by status. One of "open", "in_progress", "in_review", or "done". Omit to return tasks in all statuses.

        • Optionaltag?: string

          Return only tasks carrying this tag (matched against the canonical lowercase form).

        • Optionalteam?: string

          Team ID (tem_...). Only tasks belonging to this team are returned.

      Returns Promise<
          {
              after_cursor?: string
              | null;
              before_cursor?: string | null;
              data: {
                  agent?: string | null;
                  aggregate_version?: number | null;
                  blocked_by_count?: number;
                  closed_at?: string | null;
                  comments_count?: number;
                  created_at?: string;
                  created_by_actor?:
                      | {
                          alias?: string
                          | null;
                          id?: string | null;
                          name?: string | null;
                          profile_picture?:
                              | {
                                  file?: string
                                  | null;
                                  height?: number | null;
                                  media?: string | null;
                                  mime_type?: string | null;
                                  refresh_url?: string | null;
                                  url?: string | null;
                                  width?: number | null;
                              }
                              | null;
                      }
                      | null;
                  created_by_agent?: string
                  | null;
                  created_by_user?: string | null;
                  current_lease?:
                      | { expires_at: string; harness: string; session_name: string }
                      | null;
                  description?: string | null;
                  due_date?: string | null;
                  epic?: string | null;
                  id: string;
                  is_blocked?: boolean;
                  links?: Record<string, unknown>;
                  metadata?: Record<string, unknown>;
                  name: string;
                  org?: string | null;
                  owner_actor?:
                      | {
                          alias?: string
                          | null;
                          id?: string | null;
                          name?: string | null;
                          profile_picture?:
                              | {
                                  file?: string
                                  | null;
                                  height?: number | null;
                                  media?: string | null;
                                  mime_type?: string | null;
                                  refresh_url?: string | null;
                                  url?: string | null;
                                  width?: number | null;
                              }
                              | null;
                      }
                      | null;
                  owner_agent?: string
                  | null;
                  owner_user?: string | null;
                  parent?: string | null;
                  priority?: number;
                  sandbox?: string | null;
                  source_id?: string | null;
                  source_scope?: string | null;
                  source_type?: string | null;
                  status: string;
                  subtasks_count?: number;
                  tags?: string[];
                  team?: string | null;
                  thread?: string | null;
                  updated_at?: string;
                  user?: string | null;
              }[];
              has_more: boolean;
          },
      >

      Successful response

    • List an owner's ready tasks Returns open tasks with no unfinished blockers and no active session lease. Readiness is calculated by the server from the current task projection. It is a snapshot, not a reservation; claim a task lease before starting work. Pass explain=true to include every open task with a stable readiness reason.

      Parameters

      • user: string

        User ID (usr_...) for user-scoped tasks.

      • Optionalparams: {
            afterCursor?: string;
            assignedToMe?: boolean;
            epic?: string;
            explain?: boolean;
            limit?: number;
            org?: string;
            sourceId?: string;
            sourceScope?: string;
            sourceType?: string;
            team?: string;
        }

        Query parameters.

        • OptionalafterCursor?: string

          Opaque cursor returned by the previous page.

        • OptionalassignedToMe?: boolean

          Only include tasks assigned to the authenticated user.

        • Optionalepic?: string

          Only include tasks with this exact epic label.

        • Optionalexplain?: boolean

          Include blocked and actively leased open tasks with exclusion reasons.

        • Optionallimit?: number

          Maximum number of readiness entries to return. Capped at 100.

        • Optionalorg?: string

          Optional organization context for privileged callers.

        • OptionalsourceId?: string

          Only include tasks whose source matches this object identity.

        • OptionalsourceScope?: string

          Only include tasks whose source matches this container. Must be supplied with source_type and source_id.

        • OptionalsourceType?: string

          Only include tasks whose source matches this object kind.

        • Optionalteam?: string

          Team ID (tem_...) owning the tasks.

      Returns Promise<
          {
              after_cursor?: string;
              authoritative: boolean;
              before_cursor?: string;
              data: {
                  readiness: "leased"
                  | "ready"
                  | "blocked";
                  reason?: "open_blockers" | "active_lease" | null;
                  task: {
                      agent?: string | null;
                      aggregate_version?: number | null;
                      blocked_by_count?: number;
                      closed_at?: string | null;
                      comments_count?: number;
                      created_at?: string;
                      created_by_actor?:
                          | {
                              alias?: string
                              | null;
                              id?: string | null;
                              name?: string | null;
                              profile_picture?:
                                  | {
                                      file?: string
                                      | null;
                                      height?: number | null;
                                      media?: string | null;
                                      mime_type?: string | null;
                                      refresh_url?: string | null;
                                      url?: string | null;
                                      width?: number | null;
                                  }
                                  | null;
                          }
                          | null;
                      created_by_agent?: string
                      | null;
                      created_by_user?: string | null;
                      current_lease?:
                          | { expires_at: string; harness: string; session_name: string }
                          | null;
                      description?: string | null;
                      due_date?: string | null;
                      epic?: string | null;
                      id: string;
                      is_blocked?: boolean;
                      links?: Record<string, unknown>;
                      metadata?: Record<string, unknown>;
                      name: string;
                      org?: string | null;
                      owner_actor?:
                          | {
                              alias?: string
                              | null;
                              id?: string | null;
                              name?: string | null;
                              profile_picture?:
                                  | {
                                      file?: string
                                      | null;
                                      height?: number | null;
                                      media?: string | null;
                                      mime_type?: string | null;
                                      refresh_url?: string | null;
                                      url?: string | null;
                                      width?: number | null;
                                  }
                                  | null;
                          }
                          | null;
                      owner_agent?: string
                      | null;
                      owner_user?: string | null;
                      parent?: string | null;
                      priority?: number;
                      sandbox?: string | null;
                      source_id?: string | null;
                      source_scope?: string | null;
                      source_type?: string | null;
                      status: string;
                      subtasks_count?: number;
                      tags?: string[];
                      team?: string | null;
                      thread?: string | null;
                      updated_at?: string;
                      user?: string | null;
                  };
              }[];
              has_more: boolean;
          },
      >

      Successful response

    • Search an owner's tasks Performs a full-text search over tasks owned by the specified user or team and returns matching results. Combine q with the optional filters to narrow the result set further. When no query is provided, the endpoint behaves like a filtered list. The query field in the response echoes the effective search query. User-authenticated callers may search their personal tasks or tasks for teams they have joined. Privileged callers provide the owner in the route; the owner's organization is implied by that principal. An explicit org is optional and, when set, must match the owner's organization.

      Parameters

      • user: string

        User ID (usr_...) for user-scoped tasks.

      • Optionalparams: {
            afterCursor?: string;
            epic?: string;
            limit?: number;
            org?: string;
            ownerAgent?: string;
            ownerUser?: string;
            parent?: string;
            priority?: number;
            q?: string;
            query?: string;
            sourceId?: string;
            sourceScope?: string;
            sourceType?: string;
            status?: string;
            tag?: string;
            team?: string;
        }

        Query parameters.

        • OptionalafterCursor?: string

          Opaque cursor returned by the previous page.

        • Optionalepic?: string

          Return only tasks with this exact epic label.

        • Optionallimit?: number

          Maximum number of tasks to return. Capped at 100.

        • Optionalorg?: string

          Optional organization (org_...) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization.

        • OptionalownerAgent?: string

          Restrict results to tasks assigned to the agent with this public ID (agi_...).

        • OptionalownerUser?: string

          Restrict results to tasks assigned to the user with this public ID (usr_...).

        • Optionalparent?: string

          Return only subtasks of the given task (tsk_...), or pass none to return only top-level tasks.

        • Optionalpriority?: number

          Filter results by priority, from 0 (highest) to 4 (lowest).

        • Optionalq?: string

          Full-text search query matched against task names and descriptions. Takes precedence over query when both are provided.

        • Optionalquery?: string

          Alias for q. Use q when possible; this parameter exists for compatibility.

        • OptionalsourceId?: string

          Return only tasks whose source matches this object identity.

        • OptionalsourceScope?: string

          Return only tasks whose source matches this container. Must be supplied with source_type and source_id.

        • OptionalsourceType?: string

          Return only tasks whose source matches this object kind.

        • Optionalstatus?: string

          Filter results by status. One of "open", "in_progress", "in_review", or "done". Omit to include all statuses.

        • Optionaltag?: string

          Return only tasks carrying this tag (matched against the canonical lowercase form).

        • Optionalteam?: string

          Team ID (tem_...). Only tasks belonging to this team are searched.

      Returns Promise<
          {
              after_cursor?: string;
              before_cursor?: string;
              data: {
                  agent?: string
                  | null;
                  aggregate_version?: number | null;
                  blocked_by_count?: number;
                  closed_at?: string | null;
                  comments_count?: number;
                  created_at?: string;
                  created_by_actor?:
                      | {
                          alias?: string
                          | null;
                          id?: string | null;
                          name?: string | null;
                          profile_picture?:
                              | {
                                  file?: string
                                  | null;
                                  height?: number | null;
                                  media?: string | null;
                                  mime_type?: string | null;
                                  refresh_url?: string | null;
                                  url?: string | null;
                                  width?: number | null;
                              }
                              | null;
                      }
                      | null;
                  created_by_agent?: string
                  | null;
                  created_by_user?: string | null;
                  current_lease?:
                      | { expires_at: string; harness: string; session_name: string }
                      | null;
                  description?: string | null;
                  due_date?: string | null;
                  epic?: string | null;
                  id: string;
                  is_blocked?: boolean;
                  links?: Record<string, unknown>;
                  metadata?: Record<string, unknown>;
                  name: string;
                  org?: string | null;
                  owner_actor?:
                      | {
                          alias?: string
                          | null;
                          id?: string | null;
                          name?: string | null;
                          profile_picture?:
                              | {
                                  file?: string
                                  | null;
                                  height?: number | null;
                                  media?: string | null;
                                  mime_type?: string | null;
                                  refresh_url?: string | null;
                                  url?: string | null;
                                  width?: number | null;
                              }
                              | null;
                      }
                      | null;
                  owner_agent?: string
                  | null;
                  owner_user?: string | null;
                  parent?: string | null;
                  priority?: number;
                  sandbox?: string | null;
                  source_id?: string | null;
                  source_scope?: string | null;
                  source_type?: string | null;
                  status: string;
                  subtasks_count?: number;
                  tags?: string[];
                  team?: string | null;
                  thread?: string | null;
                  updated_at?: string;
                  user?: string | null;
              }[];
              has_more: boolean;
              query: string;
          },
      >

      Successful response

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods