Class TaskResource

constructor

• new TaskResource(http: HttpClient): TaskResource

  Parameters

  • http: HttpClient

  Returns TaskResource

Readonlyblockers

Readonlycomments

Readonlylease

Readonlylinks

activity

• activity(
      task: string,
      params?: {
          afterCursor?: string;
          agent?: string;
          limit?: number;
          org?: string;
          team?: string;
          user?: string;
      },
  ): Promise<
      {
          after_cursor?: string;
          before_cursor?: string;
          data: { event_type?: string; sentence?: string; timestamp?: string }[];
          has_more: boolean;
      },
  >

  List a task's activity Returns a bounded chronological page of activity for the specified task. App-scoped developer and server-to-server callers explicitly provide the owning team, user, or agent and org.

  Parameters

  • task: string

    Task ID (tsk_...).

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

    Query parameters.

    • OptionalafterCursor?: string

      Opaque cursor returned by the previous page.

    • Optionalagent?: string

      Explicit owning agent (agi_...) for privileged calls.

    • Optionallimit?: number

      Maximum entries to return. Capped at 100.

    • Optionalorg?: string

      Explicit organization (org_...) for privileged calls; pass null when unscoped.

    • Optionalteam?: string

      Explicit owning team (tem_...) for privileged calls.

    • Optionaluser?: string

      Explicit owning user (usr_...) for privileged calls.

  Returns Promise<
      {
          after_cursor?: string;
          before_cursor?: string;
          data: { event_type?: string; sentence?: string; timestamp?: string }[];
          has_more: boolean;
      },
  >

  Successful response

blocking

• blocking(
      task: string,
      params?: {
          afterCursor?: string;
          agent?: string;
          limit?: number;
          org?: string;
          team?: string;
          user?: string;
      },
  ): 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;
      },
  >

  List the tasks a task blocks Returns a bounded page of the tasks that the specified task is marked as blocking (the inverse of GET /tasks/{task}/blockers), newest first. The task's owner is resolved from the task itself.

  Parameters

  • task: string

    Blocking task ID (tsk_...).

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

    Query parameters.

    • OptionalafterCursor?: string

      Opaque cursor returned by the previous page.

    • Optionalagent?: string

      Explicit owning agent (agi_...) for privileged calls.

    • Optionallimit?: number

      Maximum tasks to return. Capped at 100.

    • Optionalorg?: string

      Explicit organization (org_...) for privileged calls; pass null when unscoped.

    • Optionalteam?: string

      Explicit owning team (tem_...) for privileged calls.

    • Optionaluser?: string

      Explicit owning user (usr_...) for privileged calls.

  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;
      },
  >

  Successful response

delete

• delete(task: string): Promise<void>

  Delete a task Deletes a task from task lists and detail views. The task event stream is retained for auditability, while comments are removed and direct subtasks are promoted to top-level tasks. The delete event is accepted before the read model is updated. Clients should remove the task from local collections immediately; subsequent reads converge once the projection processes the event. Authenticated users may delete tasks they can access using their session identity. App-scoped developer and server-to-server callers must explicitly supply the task's org and owner. team or user identifies that owner; when neither is present, agent identifies an agent-owned task. With a team or user owner, agent identifies the acting principal. Each reference is validated before deletion.

  Parameters

  • task: string

    Task ID (tsk_...).

  Returns Promise<void>

  Empty response. HTTP 204 is returned after the delete event is accepted.

get

• get(
      task: string,
      params?: { agent?: string; org?: string; team?: string; user?: string },
  ): Promise<Task>

  Retrieve a task Returns the full task object for the specified task ID. Authenticated users and agents resolve access through their session. App-scoped developer and server-to-server callers explicitly provide the owning team, user, or agent and org. Callers without access receive a 404.

  Parameters

  • task: string

    Task ID (tsk_...).

  • Optionalparams: { agent?: string; org?: string; team?: string; user?: string }

    Query parameters.

    • Optionalagent?: string

      Explicit owning agent (agi_...) for privileged calls.

    • Optionalorg?: string

      Explicit organization (org_...) for privileged calls; pass null when unscoped.

    • Optionalteam?: string

      Explicit owning team (tem_...) for privileged calls.

    • Optionaluser?: string

      Explicit owning user (usr_...) for privileged calls.

  Returns Promise<Task>

  The requested task.

replace

• replace(
      task: string,
      input: {
          agent?: string;
          description?: string;
          due_date?: string;
          epic?: string;
          expected_version?: number;
          lease_id?: string;
          lease_session_id?: string;
          links?: Record<string, unknown>;
          metadata?: Record<string, unknown>;
          name?: string;
          org?: string;
          owner_agent?: string;
          owner_user?: string;
          parent?: string;
          priority?: number;
          source_id?: string;
          source_scope?: string;
          source_type?: string;
          status?: string;
          tags?: string[];
          team?: string;
          user?: string;
      },
  ): Promise<Task>

  Update a task Updates the supplied fields on a task and returns the complete updated task. Authenticated users use their session identity. App-scoped developer and server-to-server callers must explicitly supply the task's org and owner. team or user identifies that owner; when neither is present, agent identifies an agent-owned task. With a team or user owner, agent identifies the acting principal. Every reference is validated before the update. A cooperating coding-session client may supply both lease_id and lease_session_id. The task aggregate fences that update against the live lease and records server-sourced session provenance. Omitting both remains a normal authorized human/API update. Supply expected_version from the latest task representation to make the update conditional. A concurrent write returns task_version_conflict.

  Parameters

  • task: string

    Task ID (tsk_...).

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

    Request body.

    • Optionalagent?: string

      Explicit agent (agi_...). It is the owner when team and user are absent; otherwise it is the acting principal.

    • Optionaldescription?: string

      Updated long-form description.

    • Optionaldue_date?: string

      Updated due date in ISO 8601 format, or null to clear it.

    • Optionalepic?: string

      Replacement grouping label. Pass null to clear it.

    • Optionalexpected_version?: number

      Aggregate version returned by the latest task read. The update fails with task_version_conflict if the task changed first.

    • Optionallease_id?: string

      Current caller-held lease UUID. Must be paired with lease_session_id.

    • Optionallease_session_id?: string

      Current coding-session UUID. Must be paired with lease_id.

    • Optionallinks?: Record<string, unknown>

      Replacement related-links object.

    • Optionalmetadata?: Record<string, unknown>

      Replacement task metadata object.

    • Optionalname?: string

      Updated display name for the task.

    • Optionalorg?: string

      Explicit organization (org_...) for a developer or server-to-server call. Pass null for an owner outside an organization.

    • Optionalowner_agent?: string

      Assign to an agent by public ID (agi_...).

    • Optionalowner_user?: string

      Assign to a user by public ID (usr_...).

    • Optionalparent?: string

      Move this task under a top-level parent (tsk_...), or pass null to promote it to a top-level task. A task that has subtasks cannot become one.

    • Optionalpriority?: number

      Updated priority from 0 (highest) to 4 (lowest).

    • Optionalsource_id?: string

      Replacement source object identity. Must be supplied with the other source fields.

    • Optionalsource_scope?: string

      Replacement source container. Pass together with source_type and source_id, or pass all three as null to clear the source.

    • Optionalsource_type?: string

      Replacement source object kind. Must be supplied with the other source fields.

    • Optionalstatus?: string

      Updated status: open, in_progress, in_review, or done.

    • Optionaltags?: string[]

      Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags.

    • Optionalteam?: string

      Explicit owning team (tem_...) for a developer or server-to-server call.

    • Optionaluser?: string

      Explicit user (usr_...) for a developer or server-to-server call. With team, this identifies the acting team member.

  Returns Promise<Task>

  The updated task.

subtasks

• subtasks(
      task: string,
      params?: {
          afterCursor?: string;
          agent?: string;
          limit?: number;
          org?: string;
          team?: string;
          user?: string;
      },
  ): 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;
      },
  >

  List a task's subtasks Returns a bounded page of the specified task's subtasks (tasks whose parent is this task), newest first. Subtasks nest exactly one level, so entries never have subtasks of their own. Privileged callers explicitly provide the owning team, user, or agent and org.

  Parameters

  • task: string

    Parent task ID (tsk_...).

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

    Query parameters.

    • OptionalafterCursor?: string

      Opaque cursor returned by the previous page.

    • Optionalagent?: string

      Explicit owning agent (agi_...) for privileged calls.

    • Optionallimit?: number

      Maximum subtasks to return. Capped at 100.

    • Optionalorg?: string

      Explicit organization (org_...) for privileged calls; pass null when unscoped.

    • Optionalteam?: string

      Explicit owning team (tem_...) for privileged calls.

    • Optionaluser?: string

      Explicit owning user (usr_...) for privileged calls.

  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;
      },
  >

  Successful response