archastro.platform.v1.resources.tasks
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: 274298b8025e 4 5from __future__ import annotations 6 7from datetime import datetime 8from typing import Any, Required, TypedDict 9 10from pydantic import BaseModel, Field 11 12from ...runtime.http_client import HttpClient, SyncHttpClient 13from ...types.tasks import Task, TaskComment, TaskSessionLease, TaskSessionLeaseSummary 14 15 16class BlockerCreateInput(TypedDict, total=False): 17 "Mark a task as blocked by another task" 18 19 agent: str | None 20 "Explicit owning agent (`agi_...`) for privileged calls." 21 blocker: Required[str] 22 "ID of the task that blocks this task (`tsk_...`)." 23 org: str | None 24 "Explicit organization (`org_...`) for privileged calls; pass null when unscoped." 25 team: str | None 26 "Explicit owning team (`tem_...`) for privileged calls." 27 user: str | None 28 "Explicit owning user (`usr_...`) for privileged calls." 29 30 31class CommentCreateInputComment(TypedDict): 32 body: str 33 "The plain-text content of the comment. Must be a non-empty string." 34 35 36class CommentCreateInput(TypedDict): 37 "Create a comment on a task" 38 39 comment: CommentCreateInputComment 40 "Parameters for the comment to create, including its body." 41 42 43class CommentReplaceInput(TypedDict): 44 "Update a task comment" 45 46 body: str 47 "Replacement body for the comment. Must be non-empty." 48 49 50class LeaseCreateInput(TypedDict, total=False): 51 "Claim a task for a coding session" 52 53 harness: Required[str] 54 "Bounded harness identifier." 55 lease_duration_seconds: int | None 56 "Requested lease lifetime in seconds; the task aggregate enforces its bounds." 57 lease_id: Required[str] 58 "Caller-generated lease UUID." 59 require_ready: bool | None 60 "Conservatively reject the claim when the current task projection has unfinished blockers." 61 session_id: Required[str] 62 "Caller-generated coding-session UUID." 63 session_name: Required[str] 64 "Human-readable coding-session label." 65 66 67class LeaseRenewInput(TypedDict, total=False): 68 "Renew a task session lease" 69 70 lease_duration_seconds: int | None 71 "Requested renewed lifetime in seconds; the task aggregate enforces its bounds." 72 lease_id: Required[str] 73 "Current caller-held lease UUID." 74 session_id: Required[str] 75 "Current coding-session UUID." 76 77 78class LinkCreateInput(TypedDict): 79 "Add an external link to a task" 80 81 external_scope: str 82 "External container ID." 83 object_id: str 84 "External object ID." 85 object_type: str 86 "External object type." 87 88 89class TaskReplaceInput(TypedDict, total=False): 90 "Update a task" 91 92 agent: str | None 93 "Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal." 94 description: str | None 95 "Updated long-form description." 96 due_date: datetime | None 97 "Updated due date in ISO 8601 format, or null to clear it." 98 epic: str | None 99 "Replacement grouping label. Pass null to clear it." 100 lease_id: str | None 101 "Current caller-held lease UUID. Must be paired with `lease_session_id`." 102 lease_session_id: str | None 103 "Current coding-session UUID. Must be paired with `lease_id`." 104 links: dict[str, Any] | None 105 "Replacement related-links object." 106 metadata: dict[str, Any] | None 107 "Replacement task metadata object." 108 name: str | None 109 "Updated display name for the task." 110 org: str | None 111 "Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization." 112 owner_agent: str | None 113 "Assign to an agent by public ID (`agi_...`)." 114 owner_user: str | None 115 "Assign to a user by public ID (`usr_...`)." 116 parent: str | None 117 "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." 118 priority: int | None 119 "Updated priority from 0 (highest) to 4 (lowest)." 120 source_id: str | None 121 "Replacement source object identity. Must be supplied with the other source fields." 122 source_scope: str | None 123 "Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source." 124 source_type: str | None 125 "Replacement source object kind. Must be supplied with the other source fields." 126 status: str | None 127 "Updated status: `open`, `in_progress`, or `done`." 128 tags: list[str] | None 129 "Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags." 130 team: str | None 131 "Explicit owning team (`tem_...`) for a developer or server-to-server call." 132 user: str | None 133 "Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member." 134 135 136class BlockerListResponseDataItemCreatedByActorProfilePicture(BaseModel): 137 file: str | None = Field( 138 default=None, 139 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 140 ) 141 height: int | None = Field( 142 default=None, description="Height of the image in pixels. `null` if not known." 143 ) 144 media: str | None = Field( 145 default=None, 146 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 147 ) 148 mime_type: str | None = Field( 149 default=None, 150 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 151 ) 152 refresh_url: str | None = Field( 153 default=None, 154 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 155 ) 156 url: str | None = Field( 157 default=None, 158 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 159 ) 160 width: int | None = Field( 161 default=None, description="Width of the image in pixels. `null` if not known." 162 ) 163 164 165class BlockerListResponseDataItemCreatedByActor(BaseModel): 166 alias: str | None = Field( 167 default=None, 168 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 169 ) 170 id: str | None = Field( 171 default=None, 172 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 173 ) 174 name: str | None = Field( 175 default=None, 176 description="Display name of the actor shown in the UI. `null` if no name is set.", 177 ) 178 profile_picture: BlockerListResponseDataItemCreatedByActorProfilePicture | None = Field( 179 default=None, 180 description="Profile picture for the actor. `null` if the actor has no profile picture.", 181 ) 182 183 184class BlockerListResponseDataItemCurrentLease(BaseModel): 185 expires_at: datetime = Field( 186 ..., description="Server-calculated lease expiry in ISO 8601 format." 187 ) 188 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 189 session_name: str = Field( 190 ..., description="Display name supplied by the coding session that holds the lease." 191 ) 192 193 194class BlockerListResponseDataItemOwnerActorProfilePicture(BaseModel): 195 file: str | None = Field( 196 default=None, 197 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 198 ) 199 height: int | None = Field( 200 default=None, description="Height of the image in pixels. `null` if not known." 201 ) 202 media: str | None = Field( 203 default=None, 204 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 205 ) 206 mime_type: str | None = Field( 207 default=None, 208 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 209 ) 210 refresh_url: str | None = Field( 211 default=None, 212 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 213 ) 214 url: str | None = Field( 215 default=None, 216 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 217 ) 218 width: int | None = Field( 219 default=None, description="Width of the image in pixels. `null` if not known." 220 ) 221 222 223class BlockerListResponseDataItemOwnerActor(BaseModel): 224 alias: str | None = Field( 225 default=None, 226 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 227 ) 228 id: str | None = Field( 229 default=None, 230 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 231 ) 232 name: str | None = Field( 233 default=None, 234 description="Display name of the actor shown in the UI. `null` if no name is set.", 235 ) 236 profile_picture: BlockerListResponseDataItemOwnerActorProfilePicture | None = Field( 237 default=None, 238 description="Profile picture for the actor. `null` if the actor has no profile picture.", 239 ) 240 241 242class BlockerListResponseDataItem(BaseModel): 243 agent: str | None = Field( 244 default=None, 245 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 246 ) 247 blocked_by_count: int | None = Field( 248 default=None, 249 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 250 ) 251 closed_at: datetime | None = Field( 252 default=None, 253 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 254 ) 255 comments_count: int | None = Field( 256 default=None, description="Total number of comments posted on this task." 257 ) 258 created_at: datetime | None = Field( 259 default=None, description="When the task was created (ISO 8601)." 260 ) 261 created_by_actor: BlockerListResponseDataItemCreatedByActor | None = Field( 262 default=None, 263 description="Resolved creator details including `id`, `name`, `alias`, and `profile_picture`. `null` if no creator is set or the creator cannot be resolved (e.g. creating agent was deleted).", 264 ) 265 created_by_agent: str | None = Field( 266 default=None, 267 description="ID of the agent that created this task (`agi_...`). `null` if the task was created by a human user, or if the creating agent was later deleted.", 268 ) 269 created_by_user: str | None = Field( 270 default=None, 271 description="ID of the user who created this task (`usr_...`). `null` if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.", 272 ) 273 current_lease: BlockerListResponseDataItemCurrentLease | None = Field( 274 default=None, 275 description="Viewer-safe live coding-session lease summary. `null` when the task is unleased or the projected lease has expired. Fencing identifiers are never included.", 276 ) 277 description: str | None = Field( 278 default=None, 279 description="Long-form description or notes for the task. `null` if no description has been provided.", 280 ) 281 due_date: datetime | None = Field( 282 default=None, 283 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 284 ) 285 epic: str | None = Field( 286 default=None, 287 description="Free-form grouping label. `null` when the task is not in an epic.", 288 ) 289 id: str = Field(..., description="Task ID (`tsk_...`).") 290 is_blocked: bool | None = Field( 291 default=None, 292 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 293 ) 294 links: dict[str, Any] | None = Field( 295 default=None, 296 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 297 ) 298 metadata: dict[str, Any] | None = Field( 299 default=None, 300 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 301 ) 302 name: str = Field(..., description="Human-readable title of the task.") 303 org: str | None = Field( 304 default=None, 305 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 306 ) 307 owner_actor: BlockerListResponseDataItemOwnerActor | None = Field( 308 default=None, 309 description="Resolved owner details including `id`, `name`, `alias`, and `profile_picture`. `null` if the task is unassigned or the owner cannot be resolved (e.g. assigned agent was deleted).", 310 ) 311 owner_agent: str | None = Field( 312 default=None, 313 description="ID of the agent assigned as owner (`agi_...`). `null` if the owner is a human user, the task is unassigned, or the assigned agent was deleted.", 314 ) 315 owner_user: str | None = Field( 316 default=None, 317 description="ID of the user assigned as owner (`usr_...`). `null` if the owner is an agent, the task is unassigned, or the assigned agent was deleted.", 318 ) 319 parent: str | None = Field( 320 default=None, 321 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 322 ) 323 priority: int | None = Field( 324 default=None, 325 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 326 ) 327 sandbox: str | None = Field( 328 default=None, 329 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 330 ) 331 source_id: str | None = Field( 332 default=None, 333 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 334 ) 335 source_scope: str | None = Field( 336 default=None, 337 description="Container of the work this task is about (for example `github.com`). `null` when the task has no source. Set together with `source_type` and `source_id`.", 338 ) 339 source_type: str | None = Field( 340 default=None, 341 description="Kind of source object (for example `repository`). `null` when the task has no source.", 342 ) 343 status: str = Field( 344 ..., 345 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 346 ) 347 subtasks_count: int | None = Field( 348 default=None, 349 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 350 ) 351 tags: list[str] | None = Field( 352 default=None, 353 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 354 ) 355 team: str | None = Field( 356 default=None, 357 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 358 ) 359 thread: str | None = Field( 360 default=None, 361 description="ID of the thread this task is bound to (`thr_...`) the conversation it was filed from, or the thread passed at creation. `null` for tasks not tied to a thread.", 362 ) 363 updated_at: datetime | None = Field( 364 default=None, description="When the task was last modified (ISO 8601)." 365 ) 366 user: str | None = Field( 367 default=None, 368 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 369 ) 370 371 372class BlockerListResponse(BaseModel): 373 """ 374 Successful response 375 """ 376 377 after_cursor: str | None = None 378 before_cursor: str | None = None 379 data: list[BlockerListResponseDataItem] 380 has_more: bool 381 382 383class CommentListResponseDataItemAuthorActorProfilePicture(BaseModel): 384 file: str | None = Field( 385 default=None, 386 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 387 ) 388 height: int | None = Field( 389 default=None, description="Height of the image in pixels. `null` if not known." 390 ) 391 media: str | None = Field( 392 default=None, 393 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 394 ) 395 mime_type: str | None = Field( 396 default=None, 397 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 398 ) 399 refresh_url: str | None = Field( 400 default=None, 401 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 402 ) 403 url: str | None = Field( 404 default=None, 405 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 406 ) 407 width: int | None = Field( 408 default=None, description="Width of the image in pixels. `null` if not known." 409 ) 410 411 412class CommentListResponseDataItemAuthorActor(BaseModel): 413 alias: str | None = Field( 414 default=None, 415 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 416 ) 417 id: str | None = Field( 418 default=None, 419 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 420 ) 421 name: str | None = Field( 422 default=None, 423 description="Display name of the actor shown in the UI. `null` if no name is set.", 424 ) 425 profile_picture: CommentListResponseDataItemAuthorActorProfilePicture | None = Field( 426 default=None, 427 description="Profile picture for the actor. `null` if the actor has no profile picture.", 428 ) 429 430 431class CommentListResponseDataItem(BaseModel): 432 author_actor: CommentListResponseDataItemAuthorActor | None = Field( 433 default=None, 434 description="Resolved author details including `id`, `name`, `alias`, and `profile_picture`. `null` if no author is set or the author cannot be resolved (e.g. authoring agent was deleted).", 435 ) 436 author_agent: str | None = Field( 437 default=None, 438 description="ID of the agent that posted this comment (`agi_...`). `null` if the author is a human user, or if the authoring agent was later deleted.", 439 ) 440 author_user: str | None = Field( 441 default=None, 442 description="ID of the user who posted this comment (`usr_...`). `null` if the author is an agent, or if author provenance was cleared after the authoring agent was deleted.", 443 ) 444 body: str = Field(..., description="Plain-text body of the comment.") 445 created_at: datetime | None = Field( 446 default=None, description="When this comment was posted (ISO 8601)." 447 ) 448 id: str = Field(..., description="Comment ID (`tcmt_...`).") 449 org: str | None = Field( 450 default=None, description="ID of the organization that owns this comment (`org_...`)." 451 ) 452 sandbox: str | None = Field( 453 default=None, 454 description="Sandbox ID this comment is scoped to. `null` for comments outside a sandbox environment.", 455 ) 456 task: str | None = Field( 457 default=None, description="ID of the task this comment belongs to (`tsk_...`)." 458 ) 459 team: str | None = Field( 460 default=None, 461 description="ID of the team the task belongs to (`tem_...`). `null` if not scoped to a team.", 462 ) 463 updated_at: datetime | None = Field( 464 default=None, description="When this comment was last edited (ISO 8601)." 465 ) 466 467 468class CommentListResponse(BaseModel): 469 """ 470 Successful response 471 """ 472 473 after_cursor: str | None = None 474 before_cursor: str | None = None 475 data: list[CommentListResponseDataItem] 476 has_more: bool 477 478 479class TaskActivityResponseDataItem(BaseModel): 480 event_type: str | None = Field( 481 default=None, 482 description='Machine-readable type of the event, e.g. `"task.status_changed"` or `"task.comment_added"`.', 483 ) 484 sentence: str | None = Field( 485 default=None, 486 description="Human-readable sentence describing the activity, suitable for display in an activity feed.", 487 ) 488 timestamp: datetime | None = Field( 489 default=None, description="When this activity event occurred (ISO 8601)." 490 ) 491 492 493class TaskActivityResponse(BaseModel): 494 """ 495 Successful response 496 """ 497 498 after_cursor: str | None = None 499 before_cursor: str | None = None 500 data: list[TaskActivityResponseDataItem] 501 has_more: bool 502 503 504class TaskBlockingResponseDataItemCreatedByActorProfilePicture(BaseModel): 505 file: str | None = Field( 506 default=None, 507 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 508 ) 509 height: int | None = Field( 510 default=None, description="Height of the image in pixels. `null` if not known." 511 ) 512 media: str | None = Field( 513 default=None, 514 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 515 ) 516 mime_type: str | None = Field( 517 default=None, 518 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 519 ) 520 refresh_url: str | None = Field( 521 default=None, 522 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 523 ) 524 url: str | None = Field( 525 default=None, 526 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 527 ) 528 width: int | None = Field( 529 default=None, description="Width of the image in pixels. `null` if not known." 530 ) 531 532 533class TaskBlockingResponseDataItemCreatedByActor(BaseModel): 534 alias: str | None = Field( 535 default=None, 536 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 537 ) 538 id: str | None = Field( 539 default=None, 540 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 541 ) 542 name: str | None = Field( 543 default=None, 544 description="Display name of the actor shown in the UI. `null` if no name is set.", 545 ) 546 profile_picture: TaskBlockingResponseDataItemCreatedByActorProfilePicture | None = Field( 547 default=None, 548 description="Profile picture for the actor. `null` if the actor has no profile picture.", 549 ) 550 551 552class TaskBlockingResponseDataItemCurrentLease(BaseModel): 553 expires_at: datetime = Field( 554 ..., description="Server-calculated lease expiry in ISO 8601 format." 555 ) 556 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 557 session_name: str = Field( 558 ..., description="Display name supplied by the coding session that holds the lease." 559 ) 560 561 562class TaskBlockingResponseDataItemOwnerActorProfilePicture(BaseModel): 563 file: str | None = Field( 564 default=None, 565 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 566 ) 567 height: int | None = Field( 568 default=None, description="Height of the image in pixels. `null` if not known." 569 ) 570 media: str | None = Field( 571 default=None, 572 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 573 ) 574 mime_type: str | None = Field( 575 default=None, 576 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 577 ) 578 refresh_url: str | None = Field( 579 default=None, 580 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 581 ) 582 url: str | None = Field( 583 default=None, 584 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 585 ) 586 width: int | None = Field( 587 default=None, description="Width of the image in pixels. `null` if not known." 588 ) 589 590 591class TaskBlockingResponseDataItemOwnerActor(BaseModel): 592 alias: str | None = Field( 593 default=None, 594 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 595 ) 596 id: str | None = Field( 597 default=None, 598 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 599 ) 600 name: str | None = Field( 601 default=None, 602 description="Display name of the actor shown in the UI. `null` if no name is set.", 603 ) 604 profile_picture: TaskBlockingResponseDataItemOwnerActorProfilePicture | None = Field( 605 default=None, 606 description="Profile picture for the actor. `null` if the actor has no profile picture.", 607 ) 608 609 610class TaskBlockingResponseDataItem(BaseModel): 611 agent: str | None = Field( 612 default=None, 613 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 614 ) 615 blocked_by_count: int | None = Field( 616 default=None, 617 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 618 ) 619 closed_at: datetime | None = Field( 620 default=None, 621 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 622 ) 623 comments_count: int | None = Field( 624 default=None, description="Total number of comments posted on this task." 625 ) 626 created_at: datetime | None = Field( 627 default=None, description="When the task was created (ISO 8601)." 628 ) 629 created_by_actor: TaskBlockingResponseDataItemCreatedByActor | None = Field( 630 default=None, 631 description="Resolved creator details including `id`, `name`, `alias`, and `profile_picture`. `null` if no creator is set or the creator cannot be resolved (e.g. creating agent was deleted).", 632 ) 633 created_by_agent: str | None = Field( 634 default=None, 635 description="ID of the agent that created this task (`agi_...`). `null` if the task was created by a human user, or if the creating agent was later deleted.", 636 ) 637 created_by_user: str | None = Field( 638 default=None, 639 description="ID of the user who created this task (`usr_...`). `null` if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.", 640 ) 641 current_lease: TaskBlockingResponseDataItemCurrentLease | None = Field( 642 default=None, 643 description="Viewer-safe live coding-session lease summary. `null` when the task is unleased or the projected lease has expired. Fencing identifiers are never included.", 644 ) 645 description: str | None = Field( 646 default=None, 647 description="Long-form description or notes for the task. `null` if no description has been provided.", 648 ) 649 due_date: datetime | None = Field( 650 default=None, 651 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 652 ) 653 epic: str | None = Field( 654 default=None, 655 description="Free-form grouping label. `null` when the task is not in an epic.", 656 ) 657 id: str = Field(..., description="Task ID (`tsk_...`).") 658 is_blocked: bool | None = Field( 659 default=None, 660 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 661 ) 662 links: dict[str, Any] | None = Field( 663 default=None, 664 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 665 ) 666 metadata: dict[str, Any] | None = Field( 667 default=None, 668 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 669 ) 670 name: str = Field(..., description="Human-readable title of the task.") 671 org: str | None = Field( 672 default=None, 673 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 674 ) 675 owner_actor: TaskBlockingResponseDataItemOwnerActor | None = Field( 676 default=None, 677 description="Resolved owner details including `id`, `name`, `alias`, and `profile_picture`. `null` if the task is unassigned or the owner cannot be resolved (e.g. assigned agent was deleted).", 678 ) 679 owner_agent: str | None = Field( 680 default=None, 681 description="ID of the agent assigned as owner (`agi_...`). `null` if the owner is a human user, the task is unassigned, or the assigned agent was deleted.", 682 ) 683 owner_user: str | None = Field( 684 default=None, 685 description="ID of the user assigned as owner (`usr_...`). `null` if the owner is an agent, the task is unassigned, or the assigned agent was deleted.", 686 ) 687 parent: str | None = Field( 688 default=None, 689 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 690 ) 691 priority: int | None = Field( 692 default=None, 693 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 694 ) 695 sandbox: str | None = Field( 696 default=None, 697 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 698 ) 699 source_id: str | None = Field( 700 default=None, 701 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 702 ) 703 source_scope: str | None = Field( 704 default=None, 705 description="Container of the work this task is about (for example `github.com`). `null` when the task has no source. Set together with `source_type` and `source_id`.", 706 ) 707 source_type: str | None = Field( 708 default=None, 709 description="Kind of source object (for example `repository`). `null` when the task has no source.", 710 ) 711 status: str = Field( 712 ..., 713 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 714 ) 715 subtasks_count: int | None = Field( 716 default=None, 717 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 718 ) 719 tags: list[str] | None = Field( 720 default=None, 721 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 722 ) 723 team: str | None = Field( 724 default=None, 725 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 726 ) 727 thread: str | None = Field( 728 default=None, 729 description="ID of the thread this task is bound to (`thr_...`) the conversation it was filed from, or the thread passed at creation. `null` for tasks not tied to a thread.", 730 ) 731 updated_at: datetime | None = Field( 732 default=None, description="When the task was last modified (ISO 8601)." 733 ) 734 user: str | None = Field( 735 default=None, 736 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 737 ) 738 739 740class TaskBlockingResponse(BaseModel): 741 """ 742 Successful response 743 """ 744 745 after_cursor: str | None = None 746 before_cursor: str | None = None 747 data: list[TaskBlockingResponseDataItem] 748 has_more: bool 749 750 751class TaskSubtasksResponseDataItemCreatedByActorProfilePicture(BaseModel): 752 file: str | None = Field( 753 default=None, 754 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 755 ) 756 height: int | None = Field( 757 default=None, description="Height of the image in pixels. `null` if not known." 758 ) 759 media: str | None = Field( 760 default=None, 761 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 762 ) 763 mime_type: str | None = Field( 764 default=None, 765 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 766 ) 767 refresh_url: str | None = Field( 768 default=None, 769 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 770 ) 771 url: str | None = Field( 772 default=None, 773 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 774 ) 775 width: int | None = Field( 776 default=None, description="Width of the image in pixels. `null` if not known." 777 ) 778 779 780class TaskSubtasksResponseDataItemCreatedByActor(BaseModel): 781 alias: str | None = Field( 782 default=None, 783 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 784 ) 785 id: str | None = Field( 786 default=None, 787 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 788 ) 789 name: str | None = Field( 790 default=None, 791 description="Display name of the actor shown in the UI. `null` if no name is set.", 792 ) 793 profile_picture: TaskSubtasksResponseDataItemCreatedByActorProfilePicture | None = Field( 794 default=None, 795 description="Profile picture for the actor. `null` if the actor has no profile picture.", 796 ) 797 798 799class TaskSubtasksResponseDataItemCurrentLease(BaseModel): 800 expires_at: datetime = Field( 801 ..., description="Server-calculated lease expiry in ISO 8601 format." 802 ) 803 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 804 session_name: str = Field( 805 ..., description="Display name supplied by the coding session that holds the lease." 806 ) 807 808 809class TaskSubtasksResponseDataItemOwnerActorProfilePicture(BaseModel): 810 file: str | None = Field( 811 default=None, 812 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 813 ) 814 height: int | None = Field( 815 default=None, description="Height of the image in pixels. `null` if not known." 816 ) 817 media: str | None = Field( 818 default=None, 819 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 820 ) 821 mime_type: str | None = Field( 822 default=None, 823 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 824 ) 825 refresh_url: str | None = Field( 826 default=None, 827 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 828 ) 829 url: str | None = Field( 830 default=None, 831 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 832 ) 833 width: int | None = Field( 834 default=None, description="Width of the image in pixels. `null` if not known." 835 ) 836 837 838class TaskSubtasksResponseDataItemOwnerActor(BaseModel): 839 alias: str | None = Field( 840 default=None, 841 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 842 ) 843 id: str | None = Field( 844 default=None, 845 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 846 ) 847 name: str | None = Field( 848 default=None, 849 description="Display name of the actor shown in the UI. `null` if no name is set.", 850 ) 851 profile_picture: TaskSubtasksResponseDataItemOwnerActorProfilePicture | None = Field( 852 default=None, 853 description="Profile picture for the actor. `null` if the actor has no profile picture.", 854 ) 855 856 857class TaskSubtasksResponseDataItem(BaseModel): 858 agent: str | None = Field( 859 default=None, 860 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 861 ) 862 blocked_by_count: int | None = Field( 863 default=None, 864 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 865 ) 866 closed_at: datetime | None = Field( 867 default=None, 868 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 869 ) 870 comments_count: int | None = Field( 871 default=None, description="Total number of comments posted on this task." 872 ) 873 created_at: datetime | None = Field( 874 default=None, description="When the task was created (ISO 8601)." 875 ) 876 created_by_actor: TaskSubtasksResponseDataItemCreatedByActor | None = Field( 877 default=None, 878 description="Resolved creator details including `id`, `name`, `alias`, and `profile_picture`. `null` if no creator is set or the creator cannot be resolved (e.g. creating agent was deleted).", 879 ) 880 created_by_agent: str | None = Field( 881 default=None, 882 description="ID of the agent that created this task (`agi_...`). `null` if the task was created by a human user, or if the creating agent was later deleted.", 883 ) 884 created_by_user: str | None = Field( 885 default=None, 886 description="ID of the user who created this task (`usr_...`). `null` if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.", 887 ) 888 current_lease: TaskSubtasksResponseDataItemCurrentLease | None = Field( 889 default=None, 890 description="Viewer-safe live coding-session lease summary. `null` when the task is unleased or the projected lease has expired. Fencing identifiers are never included.", 891 ) 892 description: str | None = Field( 893 default=None, 894 description="Long-form description or notes for the task. `null` if no description has been provided.", 895 ) 896 due_date: datetime | None = Field( 897 default=None, 898 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 899 ) 900 epic: str | None = Field( 901 default=None, 902 description="Free-form grouping label. `null` when the task is not in an epic.", 903 ) 904 id: str = Field(..., description="Task ID (`tsk_...`).") 905 is_blocked: bool | None = Field( 906 default=None, 907 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 908 ) 909 links: dict[str, Any] | None = Field( 910 default=None, 911 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 912 ) 913 metadata: dict[str, Any] | None = Field( 914 default=None, 915 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 916 ) 917 name: str = Field(..., description="Human-readable title of the task.") 918 org: str | None = Field( 919 default=None, 920 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 921 ) 922 owner_actor: TaskSubtasksResponseDataItemOwnerActor | None = Field( 923 default=None, 924 description="Resolved owner details including `id`, `name`, `alias`, and `profile_picture`. `null` if the task is unassigned or the owner cannot be resolved (e.g. assigned agent was deleted).", 925 ) 926 owner_agent: str | None = Field( 927 default=None, 928 description="ID of the agent assigned as owner (`agi_...`). `null` if the owner is a human user, the task is unassigned, or the assigned agent was deleted.", 929 ) 930 owner_user: str | None = Field( 931 default=None, 932 description="ID of the user assigned as owner (`usr_...`). `null` if the owner is an agent, the task is unassigned, or the assigned agent was deleted.", 933 ) 934 parent: str | None = Field( 935 default=None, 936 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 937 ) 938 priority: int | None = Field( 939 default=None, 940 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 941 ) 942 sandbox: str | None = Field( 943 default=None, 944 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 945 ) 946 source_id: str | None = Field( 947 default=None, 948 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 949 ) 950 source_scope: str | None = Field( 951 default=None, 952 description="Container of the work this task is about (for example `github.com`). `null` when the task has no source. Set together with `source_type` and `source_id`.", 953 ) 954 source_type: str | None = Field( 955 default=None, 956 description="Kind of source object (for example `repository`). `null` when the task has no source.", 957 ) 958 status: str = Field( 959 ..., 960 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 961 ) 962 subtasks_count: int | None = Field( 963 default=None, 964 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 965 ) 966 tags: list[str] | None = Field( 967 default=None, 968 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 969 ) 970 team: str | None = Field( 971 default=None, 972 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 973 ) 974 thread: str | None = Field( 975 default=None, 976 description="ID of the thread this task is bound to (`thr_...`) the conversation it was filed from, or the thread passed at creation. `null` for tasks not tied to a thread.", 977 ) 978 updated_at: datetime | None = Field( 979 default=None, description="When the task was last modified (ISO 8601)." 980 ) 981 user: str | None = Field( 982 default=None, 983 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 984 ) 985 986 987class TaskSubtasksResponse(BaseModel): 988 """ 989 Successful response 990 """ 991 992 after_cursor: str | None = None 993 before_cursor: str | None = None 994 data: list[TaskSubtasksResponseDataItem] 995 has_more: bool 996 997 998class AsyncBlockerResource: 999 def __init__(self, http: HttpClient): 1000 self._http = http 1001 1002 async def list( 1003 self, 1004 task: str, 1005 *, 1006 team: str | None = None, 1007 user: str | None = None, 1008 agent: str | None = None, 1009 org: str | None = None, 1010 limit: int | None = None, 1011 after_cursor: str | None = None, 1012 ) -> BlockerListResponse: 1013 """ 1014 List a task's blockers 1015 Returns a bounded page of the tasks currently marked as blocking the 1016 specified task, newest first. Blocking is informational: a blocked task 1017 can still change status, and it stops counting as blocked as soon as 1018 every blocker is done. The task's owner is resolved from the task itself. 1019 1020 Args: 1021 task: Blocked task ID (`tsk_...`). 1022 team: Explicit owning team (`tem_...`) for privileged calls. 1023 user: Explicit owning user (`usr_...`) for privileged calls. 1024 agent: Explicit owning agent (`agi_...`) for privileged calls. 1025 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1026 limit: Maximum blockers to return. Capped at 100. 1027 after_cursor: Opaque cursor returned by the previous page. 1028 1029 Returns: 1030 Successful response 1031 """ 1032 query: dict[str, object] = {} 1033 if team is not None: 1034 query["team"] = team 1035 if user is not None: 1036 query["user"] = user 1037 if agent is not None: 1038 query["agent"] = agent 1039 if org is not None: 1040 query["org"] = org 1041 if limit is not None: 1042 query["limit"] = limit 1043 if after_cursor is not None: 1044 query["after_cursor"] = after_cursor 1045 return await self._http.request( 1046 f"/api/v1/tasks/{task}/blockers", 1047 query=query, 1048 response_type=BlockerListResponse, 1049 ) 1050 1051 async def create(self, task: str, input: BlockerCreateInput) -> Task: 1052 """ 1053 Mark a task as blocked by another task 1054 Records that the task in `blocker` blocks the specified task and returns 1055 the updated task. Blocking is informational the blocked task can still 1056 change status and derived at read time, so the task stops reporting 1057 `is_blocked` as soon as every blocker is done. The blocker must belong to 1058 the same owner (team or user) as the task; self-blocking and blocking a 1059 task that already blocks the blocker (a direct cycle) are rejected. 1060 1061 Args: 1062 task: Blocked task ID (`tsk_...`). 1063 input: Request body. 1064 input.agent: Explicit owning agent (`agi_...`) for privileged calls. 1065 input.blocker: ID of the task that blocks this task (`tsk_...`). 1066 input.org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1067 input.team: Explicit owning team (`tem_...`) for privileged calls. 1068 input.user: Explicit owning user (`usr_...`) for privileged calls. 1069 1070 Returns: 1071 The updated (blocked) task. 1072 """ 1073 return await self._http.request( 1074 f"/api/v1/tasks/{task}/blockers", 1075 method="POST", 1076 body=input, 1077 response_type=Task, 1078 ) 1079 1080 async def delete(self, task: str, blocker: str) -> None: 1081 """ 1082 Remove a blocker from a task 1083 Removes the blocking relationship between the task in `blocker` and the 1084 specified task. Returns 204 No Content on success, or 404 if the given 1085 task is not currently marked as blocking this task. 1086 1087 Args: 1088 task: Blocked task ID (`tsk_...`). 1089 blocker: ID of the blocking task to remove (`tsk_...`). 1090 1091 Returns: 1092 Empty response body. HTTP 204 No Content on success. 1093 """ 1094 await self._http.request(f"/api/v1/tasks/{task}/blockers/{blocker}", method="DELETE") 1095 1096 1097class AsyncCommentResource: 1098 def __init__(self, http: HttpClient): 1099 self._http = http 1100 1101 async def list( 1102 self, 1103 task: str, 1104 *, 1105 team: str | None = None, 1106 user: str | None = None, 1107 agent: str | None = None, 1108 org: str | None = None, 1109 limit: int | None = None, 1110 after_cursor: str | None = None, 1111 ) -> CommentListResponse: 1112 """ 1113 List comments on a task 1114 Returns a bounded page of comments on the specified task, ordered by creation 1115 time ascending. App-scoped developer and server-to-server callers explicitly 1116 provide the owning `team`, `user`, or `agent` and `org`. 1117 1118 Args: 1119 task: Task ID (`tsk_...`). 1120 team: Explicit owning team (`tem_...`) for privileged calls. 1121 user: Explicit owning user (`usr_...`) for privileged calls. 1122 agent: Explicit owning agent (`agi_...`) for privileged calls. 1123 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1124 limit: Maximum comments to return. Capped at 100. 1125 after_cursor: Opaque cursor returned by the previous page. 1126 1127 Returns: 1128 Successful response 1129 """ 1130 query: dict[str, object] = {} 1131 if team is not None: 1132 query["team"] = team 1133 if user is not None: 1134 query["user"] = user 1135 if agent is not None: 1136 query["agent"] = agent 1137 if org is not None: 1138 query["org"] = org 1139 if limit is not None: 1140 query["limit"] = limit 1141 if after_cursor is not None: 1142 query["after_cursor"] = after_cursor 1143 return await self._http.request( 1144 f"/api/v1/tasks/{task}/comments", 1145 query=query, 1146 response_type=CommentListResponse, 1147 ) 1148 1149 async def create(self, task: str, input: CommentCreateInput) -> TaskComment: 1150 """ 1151 Create a comment on a task 1152 Posts a new comment on the specified task and returns the created comment. 1153 The task's owner is resolved from the task itself. 1154 1155 Args: 1156 task: Task ID (`tsk_...`). 1157 input: Request body. 1158 input.comment: Parameters for the comment to create, including its body. 1159 1160 Returns: 1161 The newly created comment. 1162 """ 1163 return await self._http.request( 1164 f"/api/v1/tasks/{task}/comments", 1165 method="POST", 1166 body=input, 1167 response_type=TaskComment, 1168 ) 1169 1170 async def delete(self, task: str, comment: str) -> None: 1171 """ 1172 Delete a task comment 1173 Permanently removes a comment from its task. This action cannot be undone. 1174 The task's owner is resolved from the task itself. 1175 Only the comment's author, an admin of the comment's organization, or an 1176 admin of the owning team may delete a comment. Returns `403 Forbidden` 1177 otherwise. 1178 1179 Args: 1180 task: Task ID (`tsk_...`). 1181 comment: Comment ID (`tcm_...`). 1182 1183 Returns: 1184 Empty body. The server responds with HTTP 204 No Content on success. 1185 """ 1186 await self._http.request(f"/api/v1/tasks/{task}/comments/{comment}", method="DELETE") 1187 1188 async def replace(self, task: str, comment: str, input: CommentReplaceInput) -> TaskComment: 1189 """ 1190 Update a task comment 1191 Replaces the body of an existing comment and returns the updated comment. 1192 The task's owner is resolved from the task itself. 1193 Only the comment's author, an admin of the comment's organization, or an 1194 admin of the owning team may edit a comment. Returns `403 Forbidden` 1195 otherwise. 1196 1197 Args: 1198 task: Task ID (`tsk_...`). 1199 comment: Comment ID (`tcm_...`). 1200 input: Request body. 1201 input.body: Replacement body for the comment. Must be non-empty. 1202 1203 Returns: 1204 The updated comment. 1205 """ 1206 return await self._http.request( 1207 f"/api/v1/tasks/{task}/comments/{comment}", 1208 method="PUT", 1209 body=input, 1210 response_type=TaskComment, 1211 ) 1212 1213 1214class AsyncLeaseResource: 1215 def __init__(self, http: HttpClient): 1216 self._http = http 1217 1218 async def remove(self, task: str) -> None: 1219 """ 1220 Release a task session lease 1221 Releases the authenticated assignee's matching live task lease. Repeating a 1222 release after the lease is absent succeeds. A different live successor lease 1223 returns a mismatch. 1224 1225 Args: 1226 task: Task ID (`tsk_...`). 1227 1228 Returns: 1229 Empty response. HTTP 204 is returned after release is accepted. 1230 """ 1231 await self._http.request(f"/api/v1/tasks/{task}/lease", method="DELETE") 1232 1233 async def list(self, task: str) -> TaskSessionLeaseSummary | None: 1234 """ 1235 Retrieve a task's current session lease 1236 Returns the authenticated assignee's viewer-safe live lease summary, or null 1237 when no live lease exists. Fencing and opaque session identifiers are never 1238 included. 1239 1240 Args: 1241 task: Task ID (`tsk_...`). 1242 1243 Returns: 1244 Viewer-safe live lease summary, or null. 1245 """ 1246 return await self._http.request( 1247 f"/api/v1/tasks/{task}/lease", 1248 response_type=TaskSessionLeaseSummary | None, 1249 ) 1250 1251 async def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: 1252 """ 1253 Claim a task for a coding session 1254 Atomically claims a user-assigned task for the authenticated user's coding 1255 session. The caller generates and retains both UUIDs. An exact retry returns 1256 the existing lease without extending it; another live holder produces a 1257 conflict. Developer and server-to-server credentials cannot impersonate the 1258 assigned user. 1259 1260 Args: 1261 task: Task ID (`tsk_...`). 1262 input: Request body. 1263 input.harness: Bounded harness identifier. 1264 input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. 1265 input.lease_id: Caller-generated lease UUID. 1266 input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. 1267 input.session_id: Caller-generated coding-session UUID. 1268 input.session_name: Human-readable coding-session label. 1269 1270 Returns: 1271 The caller-held lease, including its fencing token. 1272 """ 1273 return await self._http.request( 1274 f"/api/v1/tasks/{task}/lease", 1275 method="POST", 1276 body=input, 1277 response_type=TaskSessionLease, 1278 ) 1279 1280 async def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: 1281 """ 1282 Renew a task session lease 1283 Renews the authenticated assignee's matching live task lease. Both 1284 caller-generated UUIDs must match the aggregate's current lease. 1285 1286 Args: 1287 task: Task ID (`tsk_...`). 1288 input: Request body. 1289 input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds. 1290 input.lease_id: Current caller-held lease UUID. 1291 input.session_id: Current coding-session UUID. 1292 1293 Returns: 1294 The renewed caller-held lease. 1295 """ 1296 return await self._http.request( 1297 f"/api/v1/tasks/{task}/lease/renew", 1298 method="POST", 1299 body=input, 1300 response_type=TaskSessionLease, 1301 ) 1302 1303 1304class AsyncLinkResource: 1305 def __init__(self, http: HttpClient): 1306 self._http = http 1307 1308 async def remove(self, task: str) -> None: 1309 """ 1310 Remove an external link from a task 1311 1312 Args: 1313 task: Task ID (`tsk_...`). 1314 1315 Returns: 1316 HTTP 204 on success. 1317 """ 1318 await self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE") 1319 1320 async def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: 1321 """ 1322 Add an external link to a task 1323 1324 Args: 1325 task: Task ID (`tsk_...`). 1326 input: Request body. 1327 input.external_scope: External container ID. 1328 input.object_id: External object ID. 1329 input.object_type: External object type. 1330 1331 Returns: 1332 The created external link. 1333 """ 1334 return await self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input) 1335 1336 1337class AsyncTaskResource: 1338 def __init__(self, http: HttpClient): 1339 self._http = http 1340 self.blockers = AsyncBlockerResource(http) 1341 self.comments = AsyncCommentResource(http) 1342 self.lease = AsyncLeaseResource(http) 1343 self.links = AsyncLinkResource(http) 1344 1345 async def delete(self, task: str) -> None: 1346 """ 1347 Delete a task 1348 Deletes a task from task lists and detail views. The task event stream is 1349 retained for auditability, while comments are removed and direct subtasks 1350 are promoted to top-level tasks. 1351 The delete event is accepted before the read model is updated. Clients 1352 should remove the task from local collections immediately; subsequent reads 1353 converge once the projection processes the event. 1354 Authenticated users may delete tasks they can access using their session 1355 identity. App-scoped developer and server-to-server callers must explicitly 1356 supply the task's `org` and owner. `team` or `user` identifies that owner; 1357 when neither is present, `agent` identifies an agent-owned task. With a team 1358 or user owner, `agent` identifies the acting principal. Each reference is 1359 validated before deletion. 1360 1361 Args: 1362 task: Task ID (`tsk_...`). 1363 1364 Returns: 1365 Empty response. HTTP 204 is returned after the delete event is accepted. 1366 """ 1367 await self._http.request(f"/api/v1/tasks/{task}", method="DELETE") 1368 1369 async def get( 1370 self, 1371 task: str, 1372 *, 1373 team: str | None = None, 1374 user: str | None = None, 1375 agent: str | None = None, 1376 org: str | None = None, 1377 ) -> Task: 1378 """ 1379 Retrieve a task 1380 Returns the full task object for the specified task ID. Authenticated users 1381 and agents resolve access through their session. App-scoped developer and 1382 server-to-server callers explicitly provide the owning `team`, `user`, or `agent` and 1383 `org`. Callers without access receive a 404. 1384 1385 Args: 1386 task: Task ID (`tsk_...`). 1387 team: Explicit owning team (`tem_...`) for privileged calls. 1388 user: Explicit owning user (`usr_...`) for privileged calls. 1389 agent: Explicit owning agent (`agi_...`) for privileged calls. 1390 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1391 1392 Returns: 1393 The requested task. 1394 """ 1395 query: dict[str, object] = {} 1396 if team is not None: 1397 query["team"] = team 1398 if user is not None: 1399 query["user"] = user 1400 if agent is not None: 1401 query["agent"] = agent 1402 if org is not None: 1403 query["org"] = org 1404 return await self._http.request(f"/api/v1/tasks/{task}", query=query, response_type=Task) 1405 1406 async def replace(self, task: str, input: TaskReplaceInput) -> Task: 1407 """ 1408 Update a task 1409 Updates the supplied fields on a task and returns the complete updated task. 1410 Authenticated users use their session identity. App-scoped developer and 1411 server-to-server callers must explicitly supply the task's `org` and owner. 1412 `team` or `user` identifies that owner; when neither is present, `agent` 1413 identifies an agent-owned task. With a team or user owner, `agent` identifies 1414 the acting principal. Every reference is validated before the update. 1415 A cooperating coding-session client may supply both `lease_id` and 1416 `lease_session_id`. The task aggregate fences that update against the live 1417 lease and records server-sourced session provenance. Omitting both remains a 1418 normal authorized human/API update. 1419 1420 Args: 1421 task: Task ID (`tsk_...`). 1422 input: Request body. 1423 input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. 1424 input.description: Updated long-form description. 1425 input.due_date: Updated due date in ISO 8601 format, or null to clear it. 1426 input.epic: Replacement grouping label. Pass null to clear it. 1427 input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. 1428 input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. 1429 input.links: Replacement related-links object. 1430 input.metadata: Replacement task metadata object. 1431 input.name: Updated display name for the task. 1432 input.org: Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization. 1433 input.owner_agent: Assign to an agent by public ID (`agi_...`). 1434 input.owner_user: Assign to a user by public ID (`usr_...`). 1435 input.parent: 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. 1436 input.priority: Updated priority from 0 (highest) to 4 (lowest). 1437 input.source_id: Replacement source object identity. Must be supplied with the other source fields. 1438 input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. 1439 input.source_type: Replacement source object kind. Must be supplied with the other source fields. 1440 input.status: Updated status: `open`, `in_progress`, or `done`. 1441 input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. 1442 input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. 1443 input.user: Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member. 1444 1445 Returns: 1446 The updated task. 1447 """ 1448 return await self._http.request( 1449 f"/api/v1/tasks/{task}", 1450 method="PUT", 1451 body=input, 1452 response_type=Task, 1453 ) 1454 1455 async def activity( 1456 self, 1457 task: str, 1458 *, 1459 team: str | None = None, 1460 user: str | None = None, 1461 agent: str | None = None, 1462 org: str | None = None, 1463 limit: int | None = None, 1464 after_cursor: str | None = None, 1465 ) -> TaskActivityResponse: 1466 """ 1467 List a task's activity 1468 Returns a bounded chronological page of activity for the specified task. 1469 App-scoped developer and server-to-server callers explicitly provide the 1470 owning `team`, `user`, or `agent` and `org`. 1471 1472 Args: 1473 task: Task ID (`tsk_...`). 1474 team: Explicit owning team (`tem_...`) for privileged calls. 1475 user: Explicit owning user (`usr_...`) for privileged calls. 1476 agent: Explicit owning agent (`agi_...`) for privileged calls. 1477 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1478 limit: Maximum entries to return. Capped at 100. 1479 after_cursor: Opaque cursor returned by the previous page. 1480 1481 Returns: 1482 Successful response 1483 """ 1484 query: dict[str, object] = {} 1485 if team is not None: 1486 query["team"] = team 1487 if user is not None: 1488 query["user"] = user 1489 if agent is not None: 1490 query["agent"] = agent 1491 if org is not None: 1492 query["org"] = org 1493 if limit is not None: 1494 query["limit"] = limit 1495 if after_cursor is not None: 1496 query["after_cursor"] = after_cursor 1497 return await self._http.request( 1498 f"/api/v1/tasks/{task}/activity", 1499 query=query, 1500 response_type=TaskActivityResponse, 1501 ) 1502 1503 async def blocking( 1504 self, 1505 task: str, 1506 *, 1507 team: str | None = None, 1508 user: str | None = None, 1509 agent: str | None = None, 1510 org: str | None = None, 1511 limit: int | None = None, 1512 after_cursor: str | None = None, 1513 ) -> TaskBlockingResponse: 1514 """ 1515 List the tasks a task blocks 1516 Returns a bounded page of the tasks that the specified task is marked as 1517 blocking (the inverse of `GET /tasks/{task}/blockers`), newest first. 1518 The task's owner is resolved from the task itself. 1519 1520 Args: 1521 task: Blocking task ID (`tsk_...`). 1522 team: Explicit owning team (`tem_...`) for privileged calls. 1523 user: Explicit owning user (`usr_...`) for privileged calls. 1524 agent: Explicit owning agent (`agi_...`) for privileged calls. 1525 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1526 limit: Maximum tasks to return. Capped at 100. 1527 after_cursor: Opaque cursor returned by the previous page. 1528 1529 Returns: 1530 Successful response 1531 """ 1532 query: dict[str, object] = {} 1533 if team is not None: 1534 query["team"] = team 1535 if user is not None: 1536 query["user"] = user 1537 if agent is not None: 1538 query["agent"] = agent 1539 if org is not None: 1540 query["org"] = org 1541 if limit is not None: 1542 query["limit"] = limit 1543 if after_cursor is not None: 1544 query["after_cursor"] = after_cursor 1545 return await self._http.request( 1546 f"/api/v1/tasks/{task}/blocking", 1547 query=query, 1548 response_type=TaskBlockingResponse, 1549 ) 1550 1551 async def subtasks( 1552 self, 1553 task: str, 1554 *, 1555 team: str | None = None, 1556 user: str | None = None, 1557 agent: str | None = None, 1558 org: str | None = None, 1559 limit: int | None = None, 1560 after_cursor: str | None = None, 1561 ) -> TaskSubtasksResponse: 1562 """ 1563 List a task's subtasks 1564 Returns a bounded page of the specified task's subtasks (tasks whose 1565 `parent` is this task), newest first. Subtasks nest exactly one level, so 1566 entries never have subtasks of their own. Privileged callers explicitly 1567 provide the owning `team`, `user`, or `agent` and `org`. 1568 1569 Args: 1570 task: Parent task ID (`tsk_...`). 1571 team: Explicit owning team (`tem_...`) for privileged calls. 1572 user: Explicit owning user (`usr_...`) for privileged calls. 1573 agent: Explicit owning agent (`agi_...`) for privileged calls. 1574 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1575 limit: Maximum subtasks to return. Capped at 100. 1576 after_cursor: Opaque cursor returned by the previous page. 1577 1578 Returns: 1579 Successful response 1580 """ 1581 query: dict[str, object] = {} 1582 if team is not None: 1583 query["team"] = team 1584 if user is not None: 1585 query["user"] = user 1586 if agent is not None: 1587 query["agent"] = agent 1588 if org is not None: 1589 query["org"] = org 1590 if limit is not None: 1591 query["limit"] = limit 1592 if after_cursor is not None: 1593 query["after_cursor"] = after_cursor 1594 return await self._http.request( 1595 f"/api/v1/tasks/{task}/subtasks", 1596 query=query, 1597 response_type=TaskSubtasksResponse, 1598 ) 1599 1600 1601class BlockerResource: 1602 def __init__(self, http: SyncHttpClient): 1603 self._http = http 1604 1605 def list( 1606 self, 1607 task: str, 1608 *, 1609 team: str | None = None, 1610 user: str | None = None, 1611 agent: str | None = None, 1612 org: str | None = None, 1613 limit: int | None = None, 1614 after_cursor: str | None = None, 1615 ) -> BlockerListResponse: 1616 """ 1617 List a task's blockers 1618 Returns a bounded page of the tasks currently marked as blocking the 1619 specified task, newest first. Blocking is informational: a blocked task 1620 can still change status, and it stops counting as blocked as soon as 1621 every blocker is done. The task's owner is resolved from the task itself. 1622 1623 Args: 1624 task: Blocked task ID (`tsk_...`). 1625 team: Explicit owning team (`tem_...`) for privileged calls. 1626 user: Explicit owning user (`usr_...`) for privileged calls. 1627 agent: Explicit owning agent (`agi_...`) for privileged calls. 1628 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1629 limit: Maximum blockers to return. Capped at 100. 1630 after_cursor: Opaque cursor returned by the previous page. 1631 1632 Returns: 1633 Successful response 1634 """ 1635 query: dict[str, object] = {} 1636 if team is not None: 1637 query["team"] = team 1638 if user is not None: 1639 query["user"] = user 1640 if agent is not None: 1641 query["agent"] = agent 1642 if org is not None: 1643 query["org"] = org 1644 if limit is not None: 1645 query["limit"] = limit 1646 if after_cursor is not None: 1647 query["after_cursor"] = after_cursor 1648 return self._http.request( 1649 f"/api/v1/tasks/{task}/blockers", 1650 query=query, 1651 response_type=BlockerListResponse, 1652 ) 1653 1654 def create(self, task: str, input: BlockerCreateInput) -> Task: 1655 """ 1656 Mark a task as blocked by another task 1657 Records that the task in `blocker` blocks the specified task and returns 1658 the updated task. Blocking is informational the blocked task can still 1659 change status and derived at read time, so the task stops reporting 1660 `is_blocked` as soon as every blocker is done. The blocker must belong to 1661 the same owner (team or user) as the task; self-blocking and blocking a 1662 task that already blocks the blocker (a direct cycle) are rejected. 1663 1664 Args: 1665 task: Blocked task ID (`tsk_...`). 1666 input: Request body. 1667 input.agent: Explicit owning agent (`agi_...`) for privileged calls. 1668 input.blocker: ID of the task that blocks this task (`tsk_...`). 1669 input.org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1670 input.team: Explicit owning team (`tem_...`) for privileged calls. 1671 input.user: Explicit owning user (`usr_...`) for privileged calls. 1672 1673 Returns: 1674 The updated (blocked) task. 1675 """ 1676 return self._http.request( 1677 f"/api/v1/tasks/{task}/blockers", 1678 method="POST", 1679 body=input, 1680 response_type=Task, 1681 ) 1682 1683 def delete(self, task: str, blocker: str) -> None: 1684 """ 1685 Remove a blocker from a task 1686 Removes the blocking relationship between the task in `blocker` and the 1687 specified task. Returns 204 No Content on success, or 404 if the given 1688 task is not currently marked as blocking this task. 1689 1690 Args: 1691 task: Blocked task ID (`tsk_...`). 1692 blocker: ID of the blocking task to remove (`tsk_...`). 1693 1694 Returns: 1695 Empty response body. HTTP 204 No Content on success. 1696 """ 1697 self._http.request(f"/api/v1/tasks/{task}/blockers/{blocker}", method="DELETE") 1698 1699 1700class CommentResource: 1701 def __init__(self, http: SyncHttpClient): 1702 self._http = http 1703 1704 def list( 1705 self, 1706 task: str, 1707 *, 1708 team: str | None = None, 1709 user: str | None = None, 1710 agent: str | None = None, 1711 org: str | None = None, 1712 limit: int | None = None, 1713 after_cursor: str | None = None, 1714 ) -> CommentListResponse: 1715 """ 1716 List comments on a task 1717 Returns a bounded page of comments on the specified task, ordered by creation 1718 time ascending. App-scoped developer and server-to-server callers explicitly 1719 provide the owning `team`, `user`, or `agent` and `org`. 1720 1721 Args: 1722 task: Task ID (`tsk_...`). 1723 team: Explicit owning team (`tem_...`) for privileged calls. 1724 user: Explicit owning user (`usr_...`) for privileged calls. 1725 agent: Explicit owning agent (`agi_...`) for privileged calls. 1726 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1727 limit: Maximum comments to return. Capped at 100. 1728 after_cursor: Opaque cursor returned by the previous page. 1729 1730 Returns: 1731 Successful response 1732 """ 1733 query: dict[str, object] = {} 1734 if team is not None: 1735 query["team"] = team 1736 if user is not None: 1737 query["user"] = user 1738 if agent is not None: 1739 query["agent"] = agent 1740 if org is not None: 1741 query["org"] = org 1742 if limit is not None: 1743 query["limit"] = limit 1744 if after_cursor is not None: 1745 query["after_cursor"] = after_cursor 1746 return self._http.request( 1747 f"/api/v1/tasks/{task}/comments", 1748 query=query, 1749 response_type=CommentListResponse, 1750 ) 1751 1752 def create(self, task: str, input: CommentCreateInput) -> TaskComment: 1753 """ 1754 Create a comment on a task 1755 Posts a new comment on the specified task and returns the created comment. 1756 The task's owner is resolved from the task itself. 1757 1758 Args: 1759 task: Task ID (`tsk_...`). 1760 input: Request body. 1761 input.comment: Parameters for the comment to create, including its body. 1762 1763 Returns: 1764 The newly created comment. 1765 """ 1766 return self._http.request( 1767 f"/api/v1/tasks/{task}/comments", 1768 method="POST", 1769 body=input, 1770 response_type=TaskComment, 1771 ) 1772 1773 def delete(self, task: str, comment: str) -> None: 1774 """ 1775 Delete a task comment 1776 Permanently removes a comment from its task. This action cannot be undone. 1777 The task's owner is resolved from the task itself. 1778 Only the comment's author, an admin of the comment's organization, or an 1779 admin of the owning team may delete a comment. Returns `403 Forbidden` 1780 otherwise. 1781 1782 Args: 1783 task: Task ID (`tsk_...`). 1784 comment: Comment ID (`tcm_...`). 1785 1786 Returns: 1787 Empty body. The server responds with HTTP 204 No Content on success. 1788 """ 1789 self._http.request(f"/api/v1/tasks/{task}/comments/{comment}", method="DELETE") 1790 1791 def replace(self, task: str, comment: str, input: CommentReplaceInput) -> TaskComment: 1792 """ 1793 Update a task comment 1794 Replaces the body of an existing comment and returns the updated comment. 1795 The task's owner is resolved from the task itself. 1796 Only the comment's author, an admin of the comment's organization, or an 1797 admin of the owning team may edit a comment. Returns `403 Forbidden` 1798 otherwise. 1799 1800 Args: 1801 task: Task ID (`tsk_...`). 1802 comment: Comment ID (`tcm_...`). 1803 input: Request body. 1804 input.body: Replacement body for the comment. Must be non-empty. 1805 1806 Returns: 1807 The updated comment. 1808 """ 1809 return self._http.request( 1810 f"/api/v1/tasks/{task}/comments/{comment}", 1811 method="PUT", 1812 body=input, 1813 response_type=TaskComment, 1814 ) 1815 1816 1817class LeaseResource: 1818 def __init__(self, http: SyncHttpClient): 1819 self._http = http 1820 1821 def remove(self, task: str) -> None: 1822 """ 1823 Release a task session lease 1824 Releases the authenticated assignee's matching live task lease. Repeating a 1825 release after the lease is absent succeeds. A different live successor lease 1826 returns a mismatch. 1827 1828 Args: 1829 task: Task ID (`tsk_...`). 1830 1831 Returns: 1832 Empty response. HTTP 204 is returned after release is accepted. 1833 """ 1834 self._http.request(f"/api/v1/tasks/{task}/lease", method="DELETE") 1835 1836 def list(self, task: str) -> TaskSessionLeaseSummary | None: 1837 """ 1838 Retrieve a task's current session lease 1839 Returns the authenticated assignee's viewer-safe live lease summary, or null 1840 when no live lease exists. Fencing and opaque session identifiers are never 1841 included. 1842 1843 Args: 1844 task: Task ID (`tsk_...`). 1845 1846 Returns: 1847 Viewer-safe live lease summary, or null. 1848 """ 1849 return self._http.request( 1850 f"/api/v1/tasks/{task}/lease", 1851 response_type=TaskSessionLeaseSummary | None, 1852 ) 1853 1854 def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: 1855 """ 1856 Claim a task for a coding session 1857 Atomically claims a user-assigned task for the authenticated user's coding 1858 session. The caller generates and retains both UUIDs. An exact retry returns 1859 the existing lease without extending it; another live holder produces a 1860 conflict. Developer and server-to-server credentials cannot impersonate the 1861 assigned user. 1862 1863 Args: 1864 task: Task ID (`tsk_...`). 1865 input: Request body. 1866 input.harness: Bounded harness identifier. 1867 input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. 1868 input.lease_id: Caller-generated lease UUID. 1869 input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. 1870 input.session_id: Caller-generated coding-session UUID. 1871 input.session_name: Human-readable coding-session label. 1872 1873 Returns: 1874 The caller-held lease, including its fencing token. 1875 """ 1876 return self._http.request( 1877 f"/api/v1/tasks/{task}/lease", 1878 method="POST", 1879 body=input, 1880 response_type=TaskSessionLease, 1881 ) 1882 1883 def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: 1884 """ 1885 Renew a task session lease 1886 Renews the authenticated assignee's matching live task lease. Both 1887 caller-generated UUIDs must match the aggregate's current lease. 1888 1889 Args: 1890 task: Task ID (`tsk_...`). 1891 input: Request body. 1892 input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds. 1893 input.lease_id: Current caller-held lease UUID. 1894 input.session_id: Current coding-session UUID. 1895 1896 Returns: 1897 The renewed caller-held lease. 1898 """ 1899 return self._http.request( 1900 f"/api/v1/tasks/{task}/lease/renew", 1901 method="POST", 1902 body=input, 1903 response_type=TaskSessionLease, 1904 ) 1905 1906 1907class LinkResource: 1908 def __init__(self, http: SyncHttpClient): 1909 self._http = http 1910 1911 def remove(self, task: str) -> None: 1912 """ 1913 Remove an external link from a task 1914 1915 Args: 1916 task: Task ID (`tsk_...`). 1917 1918 Returns: 1919 HTTP 204 on success. 1920 """ 1921 self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE") 1922 1923 def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: 1924 """ 1925 Add an external link to a task 1926 1927 Args: 1928 task: Task ID (`tsk_...`). 1929 input: Request body. 1930 input.external_scope: External container ID. 1931 input.object_id: External object ID. 1932 input.object_type: External object type. 1933 1934 Returns: 1935 The created external link. 1936 """ 1937 return self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input) 1938 1939 1940class TaskResource: 1941 def __init__(self, http: SyncHttpClient): 1942 self._http = http 1943 self.blockers = BlockerResource(http) 1944 self.comments = CommentResource(http) 1945 self.lease = LeaseResource(http) 1946 self.links = LinkResource(http) 1947 1948 def delete(self, task: str) -> None: 1949 """ 1950 Delete a task 1951 Deletes a task from task lists and detail views. The task event stream is 1952 retained for auditability, while comments are removed and direct subtasks 1953 are promoted to top-level tasks. 1954 The delete event is accepted before the read model is updated. Clients 1955 should remove the task from local collections immediately; subsequent reads 1956 converge once the projection processes the event. 1957 Authenticated users may delete tasks they can access using their session 1958 identity. App-scoped developer and server-to-server callers must explicitly 1959 supply the task's `org` and owner. `team` or `user` identifies that owner; 1960 when neither is present, `agent` identifies an agent-owned task. With a team 1961 or user owner, `agent` identifies the acting principal. Each reference is 1962 validated before deletion. 1963 1964 Args: 1965 task: Task ID (`tsk_...`). 1966 1967 Returns: 1968 Empty response. HTTP 204 is returned after the delete event is accepted. 1969 """ 1970 self._http.request(f"/api/v1/tasks/{task}", method="DELETE") 1971 1972 def get( 1973 self, 1974 task: str, 1975 *, 1976 team: str | None = None, 1977 user: str | None = None, 1978 agent: str | None = None, 1979 org: str | None = None, 1980 ) -> Task: 1981 """ 1982 Retrieve a task 1983 Returns the full task object for the specified task ID. Authenticated users 1984 and agents resolve access through their session. App-scoped developer and 1985 server-to-server callers explicitly provide the owning `team`, `user`, or `agent` and 1986 `org`. Callers without access receive a 404. 1987 1988 Args: 1989 task: Task ID (`tsk_...`). 1990 team: Explicit owning team (`tem_...`) for privileged calls. 1991 user: Explicit owning user (`usr_...`) for privileged calls. 1992 agent: Explicit owning agent (`agi_...`) for privileged calls. 1993 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1994 1995 Returns: 1996 The requested task. 1997 """ 1998 query: dict[str, object] = {} 1999 if team is not None: 2000 query["team"] = team 2001 if user is not None: 2002 query["user"] = user 2003 if agent is not None: 2004 query["agent"] = agent 2005 if org is not None: 2006 query["org"] = org 2007 return self._http.request(f"/api/v1/tasks/{task}", query=query, response_type=Task) 2008 2009 def replace(self, task: str, input: TaskReplaceInput) -> Task: 2010 """ 2011 Update a task 2012 Updates the supplied fields on a task and returns the complete updated task. 2013 Authenticated users use their session identity. App-scoped developer and 2014 server-to-server callers must explicitly supply the task's `org` and owner. 2015 `team` or `user` identifies that owner; when neither is present, `agent` 2016 identifies an agent-owned task. With a team or user owner, `agent` identifies 2017 the acting principal. Every reference is validated before the update. 2018 A cooperating coding-session client may supply both `lease_id` and 2019 `lease_session_id`. The task aggregate fences that update against the live 2020 lease and records server-sourced session provenance. Omitting both remains a 2021 normal authorized human/API update. 2022 2023 Args: 2024 task: Task ID (`tsk_...`). 2025 input: Request body. 2026 input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. 2027 input.description: Updated long-form description. 2028 input.due_date: Updated due date in ISO 8601 format, or null to clear it. 2029 input.epic: Replacement grouping label. Pass null to clear it. 2030 input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. 2031 input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. 2032 input.links: Replacement related-links object. 2033 input.metadata: Replacement task metadata object. 2034 input.name: Updated display name for the task. 2035 input.org: Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization. 2036 input.owner_agent: Assign to an agent by public ID (`agi_...`). 2037 input.owner_user: Assign to a user by public ID (`usr_...`). 2038 input.parent: 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. 2039 input.priority: Updated priority from 0 (highest) to 4 (lowest). 2040 input.source_id: Replacement source object identity. Must be supplied with the other source fields. 2041 input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. 2042 input.source_type: Replacement source object kind. Must be supplied with the other source fields. 2043 input.status: Updated status: `open`, `in_progress`, or `done`. 2044 input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. 2045 input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. 2046 input.user: Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member. 2047 2048 Returns: 2049 The updated task. 2050 """ 2051 return self._http.request( 2052 f"/api/v1/tasks/{task}", 2053 method="PUT", 2054 body=input, 2055 response_type=Task, 2056 ) 2057 2058 def activity( 2059 self, 2060 task: str, 2061 *, 2062 team: str | None = None, 2063 user: str | None = None, 2064 agent: str | None = None, 2065 org: str | None = None, 2066 limit: int | None = None, 2067 after_cursor: str | None = None, 2068 ) -> TaskActivityResponse: 2069 """ 2070 List a task's activity 2071 Returns a bounded chronological page of activity for the specified task. 2072 App-scoped developer and server-to-server callers explicitly provide the 2073 owning `team`, `user`, or `agent` and `org`. 2074 2075 Args: 2076 task: Task ID (`tsk_...`). 2077 team: Explicit owning team (`tem_...`) for privileged calls. 2078 user: Explicit owning user (`usr_...`) for privileged calls. 2079 agent: Explicit owning agent (`agi_...`) for privileged calls. 2080 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2081 limit: Maximum entries to return. Capped at 100. 2082 after_cursor: Opaque cursor returned by the previous page. 2083 2084 Returns: 2085 Successful response 2086 """ 2087 query: dict[str, object] = {} 2088 if team is not None: 2089 query["team"] = team 2090 if user is not None: 2091 query["user"] = user 2092 if agent is not None: 2093 query["agent"] = agent 2094 if org is not None: 2095 query["org"] = org 2096 if limit is not None: 2097 query["limit"] = limit 2098 if after_cursor is not None: 2099 query["after_cursor"] = after_cursor 2100 return self._http.request( 2101 f"/api/v1/tasks/{task}/activity", 2102 query=query, 2103 response_type=TaskActivityResponse, 2104 ) 2105 2106 def blocking( 2107 self, 2108 task: str, 2109 *, 2110 team: str | None = None, 2111 user: str | None = None, 2112 agent: str | None = None, 2113 org: str | None = None, 2114 limit: int | None = None, 2115 after_cursor: str | None = None, 2116 ) -> TaskBlockingResponse: 2117 """ 2118 List the tasks a task blocks 2119 Returns a bounded page of the tasks that the specified task is marked as 2120 blocking (the inverse of `GET /tasks/{task}/blockers`), newest first. 2121 The task's owner is resolved from the task itself. 2122 2123 Args: 2124 task: Blocking task ID (`tsk_...`). 2125 team: Explicit owning team (`tem_...`) for privileged calls. 2126 user: Explicit owning user (`usr_...`) for privileged calls. 2127 agent: Explicit owning agent (`agi_...`) for privileged calls. 2128 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2129 limit: Maximum tasks to return. Capped at 100. 2130 after_cursor: Opaque cursor returned by the previous page. 2131 2132 Returns: 2133 Successful response 2134 """ 2135 query: dict[str, object] = {} 2136 if team is not None: 2137 query["team"] = team 2138 if user is not None: 2139 query["user"] = user 2140 if agent is not None: 2141 query["agent"] = agent 2142 if org is not None: 2143 query["org"] = org 2144 if limit is not None: 2145 query["limit"] = limit 2146 if after_cursor is not None: 2147 query["after_cursor"] = after_cursor 2148 return self._http.request( 2149 f"/api/v1/tasks/{task}/blocking", 2150 query=query, 2151 response_type=TaskBlockingResponse, 2152 ) 2153 2154 def subtasks( 2155 self, 2156 task: str, 2157 *, 2158 team: str | None = None, 2159 user: str | None = None, 2160 agent: str | None = None, 2161 org: str | None = None, 2162 limit: int | None = None, 2163 after_cursor: str | None = None, 2164 ) -> TaskSubtasksResponse: 2165 """ 2166 List a task's subtasks 2167 Returns a bounded page of the specified task's subtasks (tasks whose 2168 `parent` is this task), newest first. Subtasks nest exactly one level, so 2169 entries never have subtasks of their own. Privileged callers explicitly 2170 provide the owning `team`, `user`, or `agent` and `org`. 2171 2172 Args: 2173 task: Parent task ID (`tsk_...`). 2174 team: Explicit owning team (`tem_...`) for privileged calls. 2175 user: Explicit owning user (`usr_...`) for privileged calls. 2176 agent: Explicit owning agent (`agi_...`) for privileged calls. 2177 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2178 limit: Maximum subtasks to return. Capped at 100. 2179 after_cursor: Opaque cursor returned by the previous page. 2180 2181 Returns: 2182 Successful response 2183 """ 2184 query: dict[str, object] = {} 2185 if team is not None: 2186 query["team"] = team 2187 if user is not None: 2188 query["user"] = user 2189 if agent is not None: 2190 query["agent"] = agent 2191 if org is not None: 2192 query["org"] = org 2193 if limit is not None: 2194 query["limit"] = limit 2195 if after_cursor is not None: 2196 query["after_cursor"] = after_cursor 2197 return self._http.request( 2198 f"/api/v1/tasks/{task}/subtasks", 2199 query=query, 2200 response_type=TaskSubtasksResponse, 2201 )
class
BlockerCreateInput(typing.TypedDict):
17class BlockerCreateInput(TypedDict, total=False): 18 "Mark a task as blocked by another task" 19 20 agent: str | None 21 "Explicit owning agent (`agi_...`) for privileged calls." 22 blocker: Required[str] 23 "ID of the task that blocks this task (`tsk_...`)." 24 org: str | None 25 "Explicit organization (`org_...`) for privileged calls; pass null when unscoped." 26 team: str | None 27 "Explicit owning team (`tem_...`) for privileged calls." 28 user: str | None 29 "Explicit owning user (`usr_...`) for privileged calls."
Mark a task as blocked by another task
class
CommentCreateInputComment(typing.TypedDict):
class
CommentCreateInput(typing.TypedDict):
37class CommentCreateInput(TypedDict): 38 "Create a comment on a task" 39 40 comment: CommentCreateInputComment 41 "Parameters for the comment to create, including its body."
Create a comment on a task
class
CommentReplaceInput(typing.TypedDict):
44class CommentReplaceInput(TypedDict): 45 "Update a task comment" 46 47 body: str 48 "Replacement body for the comment. Must be non-empty."
Update a task comment
class
LeaseCreateInput(typing.TypedDict):
51class LeaseCreateInput(TypedDict, total=False): 52 "Claim a task for a coding session" 53 54 harness: Required[str] 55 "Bounded harness identifier." 56 lease_duration_seconds: int | None 57 "Requested lease lifetime in seconds; the task aggregate enforces its bounds." 58 lease_id: Required[str] 59 "Caller-generated lease UUID." 60 require_ready: bool | None 61 "Conservatively reject the claim when the current task projection has unfinished blockers." 62 session_id: Required[str] 63 "Caller-generated coding-session UUID." 64 session_name: Required[str] 65 "Human-readable coding-session label."
Claim a task for a coding session
lease_duration_seconds: int | None
Requested lease lifetime in seconds; the task aggregate enforces its bounds.
class
LeaseRenewInput(typing.TypedDict):
68class LeaseRenewInput(TypedDict, total=False): 69 "Renew a task session lease" 70 71 lease_duration_seconds: int | None 72 "Requested renewed lifetime in seconds; the task aggregate enforces its bounds." 73 lease_id: Required[str] 74 "Current caller-held lease UUID." 75 session_id: Required[str] 76 "Current coding-session UUID."
Renew a task session lease
class
LinkCreateInput(typing.TypedDict):
79class LinkCreateInput(TypedDict): 80 "Add an external link to a task" 81 82 external_scope: str 83 "External container ID." 84 object_id: str 85 "External object ID." 86 object_type: str 87 "External object type."
Add an external link to a task
class
TaskReplaceInput(typing.TypedDict):
90class TaskReplaceInput(TypedDict, total=False): 91 "Update a task" 92 93 agent: str | None 94 "Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal." 95 description: str | None 96 "Updated long-form description." 97 due_date: datetime | None 98 "Updated due date in ISO 8601 format, or null to clear it." 99 epic: str | None 100 "Replacement grouping label. Pass null to clear it." 101 lease_id: str | None 102 "Current caller-held lease UUID. Must be paired with `lease_session_id`." 103 lease_session_id: str | None 104 "Current coding-session UUID. Must be paired with `lease_id`." 105 links: dict[str, Any] | None 106 "Replacement related-links object." 107 metadata: dict[str, Any] | None 108 "Replacement task metadata object." 109 name: str | None 110 "Updated display name for the task." 111 org: str | None 112 "Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization." 113 owner_agent: str | None 114 "Assign to an agent by public ID (`agi_...`)." 115 owner_user: str | None 116 "Assign to a user by public ID (`usr_...`)." 117 parent: str | None 118 "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." 119 priority: int | None 120 "Updated priority from 0 (highest) to 4 (lowest)." 121 source_id: str | None 122 "Replacement source object identity. Must be supplied with the other source fields." 123 source_scope: str | None 124 "Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source." 125 source_type: str | None 126 "Replacement source object kind. Must be supplied with the other source fields." 127 status: str | None 128 "Updated status: `open`, `in_progress`, or `done`." 129 tags: list[str] | None 130 "Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags." 131 team: str | None 132 "Explicit owning team (`tem_...`) for a developer or server-to-server call." 133 user: str | None 134 "Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member."
Update a task
org: str | None
Explicit organization (org_...) for a developer or server-to-server call. Pass null for an owner outside an organization.
parent: str | None
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.
source_id: str | None
Replacement source object identity. Must be supplied with the other source fields.
source_scope: str | None
Replacement source container. Pass together with source_type and source_id, or pass all three as null to clear the source.
source_type: str | None
Replacement source object kind. Must be supplied with the other source fields.
user: str | None
Explicit user (usr_...) for a developer or server-to-server call. With team, this identifies the acting team member.
class
BlockerListResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
137class BlockerListResponseDataItemCreatedByActorProfilePicture(BaseModel): 138 file: str | None = Field( 139 default=None, 140 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 141 ) 142 height: int | None = Field( 143 default=None, description="Height of the image in pixels. `null` if not known." 144 ) 145 media: str | None = Field( 146 default=None, 147 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 148 ) 149 mime_type: str | None = Field( 150 default=None, 151 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 152 ) 153 refresh_url: str | None = Field( 154 default=None, 155 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 156 ) 157 url: str | None = Field( 158 default=None, 159 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 160 ) 161 width: int | None = Field( 162 default=None, description="Width of the image in pixels. `null` if not known." 163 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
file: str | None =
None
ID of the underlying storage file (fil_...). null when the image is not backed by a platform storage file.
media: str | None =
None
ID of the associated media record (med_...). null when the image is not linked to a media entity.
mime_type: str | None =
None
MIME type of the image, e.g. "image/png" or "image/jpeg". null if not known.
refresh_url: str | None =
None
Endpoint URL you can call to obtain a fresh signed url when the current one has expired. null if the URL does not require refreshing.
url: str | None =
None
Signed or public URL for downloading the image. May be time-limited; use refresh_url to obtain a new URL when this one expires.
class
BlockerListResponseDataItemCreatedByActor(pydantic.main.BaseModel):
166class BlockerListResponseDataItemCreatedByActor(BaseModel): 167 alias: str | None = Field( 168 default=None, 169 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 170 ) 171 id: str | None = Field( 172 default=None, 173 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 174 ) 175 name: str | None = Field( 176 default=None, 177 description="Display name of the actor shown in the UI. `null` if no name is set.", 178 ) 179 profile_picture: BlockerListResponseDataItemCreatedByActorProfilePicture | None = Field( 180 default=None, 181 description="Profile picture for the actor. `null` if the actor has no profile picture.", 182 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
BlockerListResponseDataItemCurrentLease(pydantic.main.BaseModel):
185class BlockerListResponseDataItemCurrentLease(BaseModel): 186 expires_at: datetime = Field( 187 ..., description="Server-calculated lease expiry in ISO 8601 format." 188 ) 189 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 190 session_name: str = Field( 191 ..., description="Display name supplied by the coding session that holds the lease." 192 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
class
BlockerListResponseDataItemOwnerActorProfilePicture(pydantic.main.BaseModel):
195class BlockerListResponseDataItemOwnerActorProfilePicture(BaseModel): 196 file: str | None = Field( 197 default=None, 198 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 199 ) 200 height: int | None = Field( 201 default=None, description="Height of the image in pixels. `null` if not known." 202 ) 203 media: str | None = Field( 204 default=None, 205 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 206 ) 207 mime_type: str | None = Field( 208 default=None, 209 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 210 ) 211 refresh_url: str | None = Field( 212 default=None, 213 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 214 ) 215 url: str | None = Field( 216 default=None, 217 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 218 ) 219 width: int | None = Field( 220 default=None, description="Width of the image in pixels. `null` if not known." 221 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
file: str | None =
None
ID of the underlying storage file (fil_...). null when the image is not backed by a platform storage file.
media: str | None =
None
ID of the associated media record (med_...). null when the image is not linked to a media entity.
mime_type: str | None =
None
MIME type of the image, e.g. "image/png" or "image/jpeg". null if not known.
refresh_url: str | None =
None
Endpoint URL you can call to obtain a fresh signed url when the current one has expired. null if the URL does not require refreshing.
url: str | None =
None
Signed or public URL for downloading the image. May be time-limited; use refresh_url to obtain a new URL when this one expires.
class
BlockerListResponseDataItemOwnerActor(pydantic.main.BaseModel):
224class BlockerListResponseDataItemOwnerActor(BaseModel): 225 alias: str | None = Field( 226 default=None, 227 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 228 ) 229 id: str | None = Field( 230 default=None, 231 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 232 ) 233 name: str | None = Field( 234 default=None, 235 description="Display name of the actor shown in the UI. `null` if no name is set.", 236 ) 237 profile_picture: BlockerListResponseDataItemOwnerActorProfilePicture | None = Field( 238 default=None, 239 description="Profile picture for the actor. `null` if the actor has no profile picture.", 240 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
BlockerListResponseDataItem(pydantic.main.BaseModel):
243class BlockerListResponseDataItem(BaseModel): 244 agent: str | None = Field( 245 default=None, 246 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 247 ) 248 blocked_by_count: int | None = Field( 249 default=None, 250 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 251 ) 252 closed_at: datetime | None = Field( 253 default=None, 254 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 255 ) 256 comments_count: int | None = Field( 257 default=None, description="Total number of comments posted on this task." 258 ) 259 created_at: datetime | None = Field( 260 default=None, description="When the task was created (ISO 8601)." 261 ) 262 created_by_actor: BlockerListResponseDataItemCreatedByActor | None = Field( 263 default=None, 264 description="Resolved creator details including `id`, `name`, `alias`, and `profile_picture`. `null` if no creator is set or the creator cannot be resolved (e.g. creating agent was deleted).", 265 ) 266 created_by_agent: str | None = Field( 267 default=None, 268 description="ID of the agent that created this task (`agi_...`). `null` if the task was created by a human user, or if the creating agent was later deleted.", 269 ) 270 created_by_user: str | None = Field( 271 default=None, 272 description="ID of the user who created this task (`usr_...`). `null` if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.", 273 ) 274 current_lease: BlockerListResponseDataItemCurrentLease | None = Field( 275 default=None, 276 description="Viewer-safe live coding-session lease summary. `null` when the task is unleased or the projected lease has expired. Fencing identifiers are never included.", 277 ) 278 description: str | None = Field( 279 default=None, 280 description="Long-form description or notes for the task. `null` if no description has been provided.", 281 ) 282 due_date: datetime | None = Field( 283 default=None, 284 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 285 ) 286 epic: str | None = Field( 287 default=None, 288 description="Free-form grouping label. `null` when the task is not in an epic.", 289 ) 290 id: str = Field(..., description="Task ID (`tsk_...`).") 291 is_blocked: bool | None = Field( 292 default=None, 293 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 294 ) 295 links: dict[str, Any] | None = Field( 296 default=None, 297 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 298 ) 299 metadata: dict[str, Any] | None = Field( 300 default=None, 301 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 302 ) 303 name: str = Field(..., description="Human-readable title of the task.") 304 org: str | None = Field( 305 default=None, 306 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 307 ) 308 owner_actor: BlockerListResponseDataItemOwnerActor | None = Field( 309 default=None, 310 description="Resolved owner details including `id`, `name`, `alias`, and `profile_picture`. `null` if the task is unassigned or the owner cannot be resolved (e.g. assigned agent was deleted).", 311 ) 312 owner_agent: str | None = Field( 313 default=None, 314 description="ID of the agent assigned as owner (`agi_...`). `null` if the owner is a human user, the task is unassigned, or the assigned agent was deleted.", 315 ) 316 owner_user: str | None = Field( 317 default=None, 318 description="ID of the user assigned as owner (`usr_...`). `null` if the owner is an agent, the task is unassigned, or the assigned agent was deleted.", 319 ) 320 parent: str | None = Field( 321 default=None, 322 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 323 ) 324 priority: int | None = Field( 325 default=None, 326 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 327 ) 328 sandbox: str | None = Field( 329 default=None, 330 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 331 ) 332 source_id: str | None = Field( 333 default=None, 334 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 335 ) 336 source_scope: str | None = Field( 337 default=None, 338 description="Container of the work this task is about (for example `github.com`). `null` when the task has no source. Set together with `source_type` and `source_id`.", 339 ) 340 source_type: str | None = Field( 341 default=None, 342 description="Kind of source object (for example `repository`). `null` when the task has no source.", 343 ) 344 status: str = Field( 345 ..., 346 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 347 ) 348 subtasks_count: int | None = Field( 349 default=None, 350 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 351 ) 352 tags: list[str] | None = Field( 353 default=None, 354 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 355 ) 356 team: str | None = Field( 357 default=None, 358 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 359 ) 360 thread: str | None = Field( 361 default=None, 362 description="ID of the thread this task is bound to (`thr_...`) the conversation it was filed from, or the thread passed at creation. `null` for tasks not tied to a thread.", 363 ) 364 updated_at: datetime | None = Field( 365 default=None, description="When the task was last modified (ISO 8601)." 366 ) 367 user: str | None = Field( 368 default=None, 369 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 370 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
blocked_by_count: int | None =
None
Number of tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report false until the next read.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", or "done".
subtasks_count: int | None =
None
Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
BlockerListResponse(pydantic.main.BaseModel):
373class BlockerListResponse(BaseModel): 374 """ 375 Successful response 376 """ 377 378 after_cursor: str | None = None 379 before_cursor: str | None = None 380 data: list[BlockerListResponseDataItem] 381 has_more: bool
Successful response
class
CommentListResponseDataItemAuthorActorProfilePicture(pydantic.main.BaseModel):
384class CommentListResponseDataItemAuthorActorProfilePicture(BaseModel): 385 file: str | None = Field( 386 default=None, 387 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 388 ) 389 height: int | None = Field( 390 default=None, description="Height of the image in pixels. `null` if not known." 391 ) 392 media: str | None = Field( 393 default=None, 394 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 395 ) 396 mime_type: str | None = Field( 397 default=None, 398 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 399 ) 400 refresh_url: str | None = Field( 401 default=None, 402 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 403 ) 404 url: str | None = Field( 405 default=None, 406 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 407 ) 408 width: int | None = Field( 409 default=None, description="Width of the image in pixels. `null` if not known." 410 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
file: str | None =
None
ID of the underlying storage file (fil_...). null when the image is not backed by a platform storage file.
media: str | None =
None
ID of the associated media record (med_...). null when the image is not linked to a media entity.
mime_type: str | None =
None
MIME type of the image, e.g. "image/png" or "image/jpeg". null if not known.
refresh_url: str | None =
None
Endpoint URL you can call to obtain a fresh signed url when the current one has expired. null if the URL does not require refreshing.
url: str | None =
None
Signed or public URL for downloading the image. May be time-limited; use refresh_url to obtain a new URL when this one expires.
class
CommentListResponseDataItemAuthorActor(pydantic.main.BaseModel):
413class CommentListResponseDataItemAuthorActor(BaseModel): 414 alias: str | None = Field( 415 default=None, 416 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 417 ) 418 id: str | None = Field( 419 default=None, 420 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 421 ) 422 name: str | None = Field( 423 default=None, 424 description="Display name of the actor shown in the UI. `null` if no name is set.", 425 ) 426 profile_picture: CommentListResponseDataItemAuthorActorProfilePicture | None = Field( 427 default=None, 428 description="Profile picture for the actor. `null` if the actor has no profile picture.", 429 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
CommentListResponseDataItem(pydantic.main.BaseModel):
432class CommentListResponseDataItem(BaseModel): 433 author_actor: CommentListResponseDataItemAuthorActor | None = Field( 434 default=None, 435 description="Resolved author details including `id`, `name`, `alias`, and `profile_picture`. `null` if no author is set or the author cannot be resolved (e.g. authoring agent was deleted).", 436 ) 437 author_agent: str | None = Field( 438 default=None, 439 description="ID of the agent that posted this comment (`agi_...`). `null` if the author is a human user, or if the authoring agent was later deleted.", 440 ) 441 author_user: str | None = Field( 442 default=None, 443 description="ID of the user who posted this comment (`usr_...`). `null` if the author is an agent, or if author provenance was cleared after the authoring agent was deleted.", 444 ) 445 body: str = Field(..., description="Plain-text body of the comment.") 446 created_at: datetime | None = Field( 447 default=None, description="When this comment was posted (ISO 8601)." 448 ) 449 id: str = Field(..., description="Comment ID (`tcmt_...`).") 450 org: str | None = Field( 451 default=None, description="ID of the organization that owns this comment (`org_...`)." 452 ) 453 sandbox: str | None = Field( 454 default=None, 455 description="Sandbox ID this comment is scoped to. `null` for comments outside a sandbox environment.", 456 ) 457 task: str | None = Field( 458 default=None, description="ID of the task this comment belongs to (`tsk_...`)." 459 ) 460 team: str | None = Field( 461 default=None, 462 description="ID of the team the task belongs to (`tem_...`). `null` if not scoped to a team.", 463 ) 464 updated_at: datetime | None = Field( 465 default=None, description="When this comment was last edited (ISO 8601)." 466 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
class
CommentListResponse(pydantic.main.BaseModel):
469class CommentListResponse(BaseModel): 470 """ 471 Successful response 472 """ 473 474 after_cursor: str | None = None 475 before_cursor: str | None = None 476 data: list[CommentListResponseDataItem] 477 has_more: bool
Successful response
class
TaskActivityResponseDataItem(pydantic.main.BaseModel):
480class TaskActivityResponseDataItem(BaseModel): 481 event_type: str | None = Field( 482 default=None, 483 description='Machine-readable type of the event, e.g. `"task.status_changed"` or `"task.comment_added"`.', 484 ) 485 sentence: str | None = Field( 486 default=None, 487 description="Human-readable sentence describing the activity, suitable for display in an activity feed.", 488 ) 489 timestamp: datetime | None = Field( 490 default=None, description="When this activity event occurred (ISO 8601)." 491 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
event_type: str | None =
None
Machine-readable type of the event, e.g. "task.status_changed" or "task.comment_added".
class
TaskActivityResponse(pydantic.main.BaseModel):
494class TaskActivityResponse(BaseModel): 495 """ 496 Successful response 497 """ 498 499 after_cursor: str | None = None 500 before_cursor: str | None = None 501 data: list[TaskActivityResponseDataItem] 502 has_more: bool
Successful response
class
TaskBlockingResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
505class TaskBlockingResponseDataItemCreatedByActorProfilePicture(BaseModel): 506 file: str | None = Field( 507 default=None, 508 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 509 ) 510 height: int | None = Field( 511 default=None, description="Height of the image in pixels. `null` if not known." 512 ) 513 media: str | None = Field( 514 default=None, 515 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 516 ) 517 mime_type: str | None = Field( 518 default=None, 519 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 520 ) 521 refresh_url: str | None = Field( 522 default=None, 523 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 524 ) 525 url: str | None = Field( 526 default=None, 527 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 528 ) 529 width: int | None = Field( 530 default=None, description="Width of the image in pixels. `null` if not known." 531 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
file: str | None =
None
ID of the underlying storage file (fil_...). null when the image is not backed by a platform storage file.
media: str | None =
None
ID of the associated media record (med_...). null when the image is not linked to a media entity.
mime_type: str | None =
None
MIME type of the image, e.g. "image/png" or "image/jpeg". null if not known.
refresh_url: str | None =
None
Endpoint URL you can call to obtain a fresh signed url when the current one has expired. null if the URL does not require refreshing.
url: str | None =
None
Signed or public URL for downloading the image. May be time-limited; use refresh_url to obtain a new URL when this one expires.
class
TaskBlockingResponseDataItemCreatedByActor(pydantic.main.BaseModel):
534class TaskBlockingResponseDataItemCreatedByActor(BaseModel): 535 alias: str | None = Field( 536 default=None, 537 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 538 ) 539 id: str | None = Field( 540 default=None, 541 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 542 ) 543 name: str | None = Field( 544 default=None, 545 description="Display name of the actor shown in the UI. `null` if no name is set.", 546 ) 547 profile_picture: TaskBlockingResponseDataItemCreatedByActorProfilePicture | None = Field( 548 default=None, 549 description="Profile picture for the actor. `null` if the actor has no profile picture.", 550 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
TaskBlockingResponseDataItemCurrentLease(pydantic.main.BaseModel):
553class TaskBlockingResponseDataItemCurrentLease(BaseModel): 554 expires_at: datetime = Field( 555 ..., description="Server-calculated lease expiry in ISO 8601 format." 556 ) 557 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 558 session_name: str = Field( 559 ..., description="Display name supplied by the coding session that holds the lease." 560 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
class
TaskBlockingResponseDataItemOwnerActorProfilePicture(pydantic.main.BaseModel):
563class TaskBlockingResponseDataItemOwnerActorProfilePicture(BaseModel): 564 file: str | None = Field( 565 default=None, 566 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 567 ) 568 height: int | None = Field( 569 default=None, description="Height of the image in pixels. `null` if not known." 570 ) 571 media: str | None = Field( 572 default=None, 573 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 574 ) 575 mime_type: str | None = Field( 576 default=None, 577 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 578 ) 579 refresh_url: str | None = Field( 580 default=None, 581 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 582 ) 583 url: str | None = Field( 584 default=None, 585 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 586 ) 587 width: int | None = Field( 588 default=None, description="Width of the image in pixels. `null` if not known." 589 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
file: str | None =
None
ID of the underlying storage file (fil_...). null when the image is not backed by a platform storage file.
media: str | None =
None
ID of the associated media record (med_...). null when the image is not linked to a media entity.
mime_type: str | None =
None
MIME type of the image, e.g. "image/png" or "image/jpeg". null if not known.
refresh_url: str | None =
None
Endpoint URL you can call to obtain a fresh signed url when the current one has expired. null if the URL does not require refreshing.
url: str | None =
None
Signed or public URL for downloading the image. May be time-limited; use refresh_url to obtain a new URL when this one expires.
class
TaskBlockingResponseDataItemOwnerActor(pydantic.main.BaseModel):
592class TaskBlockingResponseDataItemOwnerActor(BaseModel): 593 alias: str | None = Field( 594 default=None, 595 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 596 ) 597 id: str | None = Field( 598 default=None, 599 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 600 ) 601 name: str | None = Field( 602 default=None, 603 description="Display name of the actor shown in the UI. `null` if no name is set.", 604 ) 605 profile_picture: TaskBlockingResponseDataItemOwnerActorProfilePicture | None = Field( 606 default=None, 607 description="Profile picture for the actor. `null` if the actor has no profile picture.", 608 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
TaskBlockingResponseDataItem(pydantic.main.BaseModel):
611class TaskBlockingResponseDataItem(BaseModel): 612 agent: str | None = Field( 613 default=None, 614 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 615 ) 616 blocked_by_count: int | None = Field( 617 default=None, 618 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 619 ) 620 closed_at: datetime | None = Field( 621 default=None, 622 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 623 ) 624 comments_count: int | None = Field( 625 default=None, description="Total number of comments posted on this task." 626 ) 627 created_at: datetime | None = Field( 628 default=None, description="When the task was created (ISO 8601)." 629 ) 630 created_by_actor: TaskBlockingResponseDataItemCreatedByActor | None = Field( 631 default=None, 632 description="Resolved creator details including `id`, `name`, `alias`, and `profile_picture`. `null` if no creator is set or the creator cannot be resolved (e.g. creating agent was deleted).", 633 ) 634 created_by_agent: str | None = Field( 635 default=None, 636 description="ID of the agent that created this task (`agi_...`). `null` if the task was created by a human user, or if the creating agent was later deleted.", 637 ) 638 created_by_user: str | None = Field( 639 default=None, 640 description="ID of the user who created this task (`usr_...`). `null` if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.", 641 ) 642 current_lease: TaskBlockingResponseDataItemCurrentLease | None = Field( 643 default=None, 644 description="Viewer-safe live coding-session lease summary. `null` when the task is unleased or the projected lease has expired. Fencing identifiers are never included.", 645 ) 646 description: str | None = Field( 647 default=None, 648 description="Long-form description or notes for the task. `null` if no description has been provided.", 649 ) 650 due_date: datetime | None = Field( 651 default=None, 652 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 653 ) 654 epic: str | None = Field( 655 default=None, 656 description="Free-form grouping label. `null` when the task is not in an epic.", 657 ) 658 id: str = Field(..., description="Task ID (`tsk_...`).") 659 is_blocked: bool | None = Field( 660 default=None, 661 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 662 ) 663 links: dict[str, Any] | None = Field( 664 default=None, 665 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 666 ) 667 metadata: dict[str, Any] | None = Field( 668 default=None, 669 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 670 ) 671 name: str = Field(..., description="Human-readable title of the task.") 672 org: str | None = Field( 673 default=None, 674 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 675 ) 676 owner_actor: TaskBlockingResponseDataItemOwnerActor | None = Field( 677 default=None, 678 description="Resolved owner details including `id`, `name`, `alias`, and `profile_picture`. `null` if the task is unassigned or the owner cannot be resolved (e.g. assigned agent was deleted).", 679 ) 680 owner_agent: str | None = Field( 681 default=None, 682 description="ID of the agent assigned as owner (`agi_...`). `null` if the owner is a human user, the task is unassigned, or the assigned agent was deleted.", 683 ) 684 owner_user: str | None = Field( 685 default=None, 686 description="ID of the user assigned as owner (`usr_...`). `null` if the owner is an agent, the task is unassigned, or the assigned agent was deleted.", 687 ) 688 parent: str | None = Field( 689 default=None, 690 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 691 ) 692 priority: int | None = Field( 693 default=None, 694 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 695 ) 696 sandbox: str | None = Field( 697 default=None, 698 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 699 ) 700 source_id: str | None = Field( 701 default=None, 702 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 703 ) 704 source_scope: str | None = Field( 705 default=None, 706 description="Container of the work this task is about (for example `github.com`). `null` when the task has no source. Set together with `source_type` and `source_id`.", 707 ) 708 source_type: str | None = Field( 709 default=None, 710 description="Kind of source object (for example `repository`). `null` when the task has no source.", 711 ) 712 status: str = Field( 713 ..., 714 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 715 ) 716 subtasks_count: int | None = Field( 717 default=None, 718 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 719 ) 720 tags: list[str] | None = Field( 721 default=None, 722 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 723 ) 724 team: str | None = Field( 725 default=None, 726 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 727 ) 728 thread: str | None = Field( 729 default=None, 730 description="ID of the thread this task is bound to (`thr_...`) the conversation it was filed from, or the thread passed at creation. `null` for tasks not tied to a thread.", 731 ) 732 updated_at: datetime | None = Field( 733 default=None, description="When the task was last modified (ISO 8601)." 734 ) 735 user: str | None = Field( 736 default=None, 737 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 738 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
blocked_by_count: int | None =
None
Number of tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report false until the next read.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", or "done".
subtasks_count: int | None =
None
Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
TaskBlockingResponse(pydantic.main.BaseModel):
741class TaskBlockingResponse(BaseModel): 742 """ 743 Successful response 744 """ 745 746 after_cursor: str | None = None 747 before_cursor: str | None = None 748 data: list[TaskBlockingResponseDataItem] 749 has_more: bool
Successful response
class
TaskSubtasksResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
752class TaskSubtasksResponseDataItemCreatedByActorProfilePicture(BaseModel): 753 file: str | None = Field( 754 default=None, 755 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 756 ) 757 height: int | None = Field( 758 default=None, description="Height of the image in pixels. `null` if not known." 759 ) 760 media: str | None = Field( 761 default=None, 762 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 763 ) 764 mime_type: str | None = Field( 765 default=None, 766 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 767 ) 768 refresh_url: str | None = Field( 769 default=None, 770 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 771 ) 772 url: str | None = Field( 773 default=None, 774 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 775 ) 776 width: int | None = Field( 777 default=None, description="Width of the image in pixels. `null` if not known." 778 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
file: str | None =
None
ID of the underlying storage file (fil_...). null when the image is not backed by a platform storage file.
media: str | None =
None
ID of the associated media record (med_...). null when the image is not linked to a media entity.
mime_type: str | None =
None
MIME type of the image, e.g. "image/png" or "image/jpeg". null if not known.
refresh_url: str | None =
None
Endpoint URL you can call to obtain a fresh signed url when the current one has expired. null if the URL does not require refreshing.
url: str | None =
None
Signed or public URL for downloading the image. May be time-limited; use refresh_url to obtain a new URL when this one expires.
class
TaskSubtasksResponseDataItemCreatedByActor(pydantic.main.BaseModel):
781class TaskSubtasksResponseDataItemCreatedByActor(BaseModel): 782 alias: str | None = Field( 783 default=None, 784 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 785 ) 786 id: str | None = Field( 787 default=None, 788 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 789 ) 790 name: str | None = Field( 791 default=None, 792 description="Display name of the actor shown in the UI. `null` if no name is set.", 793 ) 794 profile_picture: TaskSubtasksResponseDataItemCreatedByActorProfilePicture | None = Field( 795 default=None, 796 description="Profile picture for the actor. `null` if the actor has no profile picture.", 797 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
TaskSubtasksResponseDataItemCurrentLease(pydantic.main.BaseModel):
800class TaskSubtasksResponseDataItemCurrentLease(BaseModel): 801 expires_at: datetime = Field( 802 ..., description="Server-calculated lease expiry in ISO 8601 format." 803 ) 804 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 805 session_name: str = Field( 806 ..., description="Display name supplied by the coding session that holds the lease." 807 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
class
TaskSubtasksResponseDataItemOwnerActorProfilePicture(pydantic.main.BaseModel):
810class TaskSubtasksResponseDataItemOwnerActorProfilePicture(BaseModel): 811 file: str | None = Field( 812 default=None, 813 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 814 ) 815 height: int | None = Field( 816 default=None, description="Height of the image in pixels. `null` if not known." 817 ) 818 media: str | None = Field( 819 default=None, 820 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 821 ) 822 mime_type: str | None = Field( 823 default=None, 824 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 825 ) 826 refresh_url: str | None = Field( 827 default=None, 828 description="Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.", 829 ) 830 url: str | None = Field( 831 default=None, 832 description="Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.", 833 ) 834 width: int | None = Field( 835 default=None, description="Width of the image in pixels. `null` if not known." 836 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
file: str | None =
None
ID of the underlying storage file (fil_...). null when the image is not backed by a platform storage file.
media: str | None =
None
ID of the associated media record (med_...). null when the image is not linked to a media entity.
mime_type: str | None =
None
MIME type of the image, e.g. "image/png" or "image/jpeg". null if not known.
refresh_url: str | None =
None
Endpoint URL you can call to obtain a fresh signed url when the current one has expired. null if the URL does not require refreshing.
url: str | None =
None
Signed or public URL for downloading the image. May be time-limited; use refresh_url to obtain a new URL when this one expires.
class
TaskSubtasksResponseDataItemOwnerActor(pydantic.main.BaseModel):
839class TaskSubtasksResponseDataItemOwnerActor(BaseModel): 840 alias: str | None = Field( 841 default=None, 842 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 843 ) 844 id: str | None = Field( 845 default=None, 846 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 847 ) 848 name: str | None = Field( 849 default=None, 850 description="Display name of the actor shown in the UI. `null` if no name is set.", 851 ) 852 profile_picture: TaskSubtasksResponseDataItemOwnerActorProfilePicture | None = Field( 853 default=None, 854 description="Profile picture for the actor. `null` if the actor has no profile picture.", 855 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
TaskSubtasksResponseDataItem(pydantic.main.BaseModel):
858class TaskSubtasksResponseDataItem(BaseModel): 859 agent: str | None = Field( 860 default=None, 861 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 862 ) 863 blocked_by_count: int | None = Field( 864 default=None, 865 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 866 ) 867 closed_at: datetime | None = Field( 868 default=None, 869 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 870 ) 871 comments_count: int | None = Field( 872 default=None, description="Total number of comments posted on this task." 873 ) 874 created_at: datetime | None = Field( 875 default=None, description="When the task was created (ISO 8601)." 876 ) 877 created_by_actor: TaskSubtasksResponseDataItemCreatedByActor | None = Field( 878 default=None, 879 description="Resolved creator details including `id`, `name`, `alias`, and `profile_picture`. `null` if no creator is set or the creator cannot be resolved (e.g. creating agent was deleted).", 880 ) 881 created_by_agent: str | None = Field( 882 default=None, 883 description="ID of the agent that created this task (`agi_...`). `null` if the task was created by a human user, or if the creating agent was later deleted.", 884 ) 885 created_by_user: str | None = Field( 886 default=None, 887 description="ID of the user who created this task (`usr_...`). `null` if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.", 888 ) 889 current_lease: TaskSubtasksResponseDataItemCurrentLease | None = Field( 890 default=None, 891 description="Viewer-safe live coding-session lease summary. `null` when the task is unleased or the projected lease has expired. Fencing identifiers are never included.", 892 ) 893 description: str | None = Field( 894 default=None, 895 description="Long-form description or notes for the task. `null` if no description has been provided.", 896 ) 897 due_date: datetime | None = Field( 898 default=None, 899 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 900 ) 901 epic: str | None = Field( 902 default=None, 903 description="Free-form grouping label. `null` when the task is not in an epic.", 904 ) 905 id: str = Field(..., description="Task ID (`tsk_...`).") 906 is_blocked: bool | None = Field( 907 default=None, 908 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 909 ) 910 links: dict[str, Any] | None = Field( 911 default=None, 912 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 913 ) 914 metadata: dict[str, Any] | None = Field( 915 default=None, 916 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 917 ) 918 name: str = Field(..., description="Human-readable title of the task.") 919 org: str | None = Field( 920 default=None, 921 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 922 ) 923 owner_actor: TaskSubtasksResponseDataItemOwnerActor | None = Field( 924 default=None, 925 description="Resolved owner details including `id`, `name`, `alias`, and `profile_picture`. `null` if the task is unassigned or the owner cannot be resolved (e.g. assigned agent was deleted).", 926 ) 927 owner_agent: str | None = Field( 928 default=None, 929 description="ID of the agent assigned as owner (`agi_...`). `null` if the owner is a human user, the task is unassigned, or the assigned agent was deleted.", 930 ) 931 owner_user: str | None = Field( 932 default=None, 933 description="ID of the user assigned as owner (`usr_...`). `null` if the owner is an agent, the task is unassigned, or the assigned agent was deleted.", 934 ) 935 parent: str | None = Field( 936 default=None, 937 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 938 ) 939 priority: int | None = Field( 940 default=None, 941 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 942 ) 943 sandbox: str | None = Field( 944 default=None, 945 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 946 ) 947 source_id: str | None = Field( 948 default=None, 949 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 950 ) 951 source_scope: str | None = Field( 952 default=None, 953 description="Container of the work this task is about (for example `github.com`). `null` when the task has no source. Set together with `source_type` and `source_id`.", 954 ) 955 source_type: str | None = Field( 956 default=None, 957 description="Kind of source object (for example `repository`). `null` when the task has no source.", 958 ) 959 status: str = Field( 960 ..., 961 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 962 ) 963 subtasks_count: int | None = Field( 964 default=None, 965 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 966 ) 967 tags: list[str] | None = Field( 968 default=None, 969 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 970 ) 971 team: str | None = Field( 972 default=None, 973 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 974 ) 975 thread: str | None = Field( 976 default=None, 977 description="ID of the thread this task is bound to (`thr_...`) the conversation it was filed from, or the thread passed at creation. `null` for tasks not tied to a thread.", 978 ) 979 updated_at: datetime | None = Field( 980 default=None, description="When the task was last modified (ISO 8601)." 981 ) 982 user: str | None = Field( 983 default=None, 984 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 985 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
blocked_by_count: int | None =
None
Number of tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report false until the next read.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", or "done".
subtasks_count: int | None =
None
Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
TaskSubtasksResponse(pydantic.main.BaseModel):
988class TaskSubtasksResponse(BaseModel): 989 """ 990 Successful response 991 """ 992 993 after_cursor: str | None = None 994 before_cursor: str | None = None 995 data: list[TaskSubtasksResponseDataItem] 996 has_more: bool
Successful response
class
AsyncBlockerResource:
999class AsyncBlockerResource: 1000 def __init__(self, http: HttpClient): 1001 self._http = http 1002 1003 async def list( 1004 self, 1005 task: str, 1006 *, 1007 team: str | None = None, 1008 user: str | None = None, 1009 agent: str | None = None, 1010 org: str | None = None, 1011 limit: int | None = None, 1012 after_cursor: str | None = None, 1013 ) -> BlockerListResponse: 1014 """ 1015 List a task's blockers 1016 Returns a bounded page of the tasks currently marked as blocking the 1017 specified task, newest first. Blocking is informational: a blocked task 1018 can still change status, and it stops counting as blocked as soon as 1019 every blocker is done. The task's owner is resolved from the task itself. 1020 1021 Args: 1022 task: Blocked task ID (`tsk_...`). 1023 team: Explicit owning team (`tem_...`) for privileged calls. 1024 user: Explicit owning user (`usr_...`) for privileged calls. 1025 agent: Explicit owning agent (`agi_...`) for privileged calls. 1026 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1027 limit: Maximum blockers to return. Capped at 100. 1028 after_cursor: Opaque cursor returned by the previous page. 1029 1030 Returns: 1031 Successful response 1032 """ 1033 query: dict[str, object] = {} 1034 if team is not None: 1035 query["team"] = team 1036 if user is not None: 1037 query["user"] = user 1038 if agent is not None: 1039 query["agent"] = agent 1040 if org is not None: 1041 query["org"] = org 1042 if limit is not None: 1043 query["limit"] = limit 1044 if after_cursor is not None: 1045 query["after_cursor"] = after_cursor 1046 return await self._http.request( 1047 f"/api/v1/tasks/{task}/blockers", 1048 query=query, 1049 response_type=BlockerListResponse, 1050 ) 1051 1052 async def create(self, task: str, input: BlockerCreateInput) -> Task: 1053 """ 1054 Mark a task as blocked by another task 1055 Records that the task in `blocker` blocks the specified task and returns 1056 the updated task. Blocking is informational the blocked task can still 1057 change status and derived at read time, so the task stops reporting 1058 `is_blocked` as soon as every blocker is done. The blocker must belong to 1059 the same owner (team or user) as the task; self-blocking and blocking a 1060 task that already blocks the blocker (a direct cycle) are rejected. 1061 1062 Args: 1063 task: Blocked task ID (`tsk_...`). 1064 input: Request body. 1065 input.agent: Explicit owning agent (`agi_...`) for privileged calls. 1066 input.blocker: ID of the task that blocks this task (`tsk_...`). 1067 input.org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1068 input.team: Explicit owning team (`tem_...`) for privileged calls. 1069 input.user: Explicit owning user (`usr_...`) for privileged calls. 1070 1071 Returns: 1072 The updated (blocked) task. 1073 """ 1074 return await self._http.request( 1075 f"/api/v1/tasks/{task}/blockers", 1076 method="POST", 1077 body=input, 1078 response_type=Task, 1079 ) 1080 1081 async def delete(self, task: str, blocker: str) -> None: 1082 """ 1083 Remove a blocker from a task 1084 Removes the blocking relationship between the task in `blocker` and the 1085 specified task. Returns 204 No Content on success, or 404 if the given 1086 task is not currently marked as blocking this task. 1087 1088 Args: 1089 task: Blocked task ID (`tsk_...`). 1090 blocker: ID of the blocking task to remove (`tsk_...`). 1091 1092 Returns: 1093 Empty response body. HTTP 204 No Content on success. 1094 """ 1095 await self._http.request(f"/api/v1/tasks/{task}/blockers/{blocker}", method="DELETE")
AsyncBlockerResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> BlockerListResponse:
1003 async def list( 1004 self, 1005 task: str, 1006 *, 1007 team: str | None = None, 1008 user: str | None = None, 1009 agent: str | None = None, 1010 org: str | None = None, 1011 limit: int | None = None, 1012 after_cursor: str | None = None, 1013 ) -> BlockerListResponse: 1014 """ 1015 List a task's blockers 1016 Returns a bounded page of the tasks currently marked as blocking the 1017 specified task, newest first. Blocking is informational: a blocked task 1018 can still change status, and it stops counting as blocked as soon as 1019 every blocker is done. The task's owner is resolved from the task itself. 1020 1021 Args: 1022 task: Blocked task ID (`tsk_...`). 1023 team: Explicit owning team (`tem_...`) for privileged calls. 1024 user: Explicit owning user (`usr_...`) for privileged calls. 1025 agent: Explicit owning agent (`agi_...`) for privileged calls. 1026 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1027 limit: Maximum blockers to return. Capped at 100. 1028 after_cursor: Opaque cursor returned by the previous page. 1029 1030 Returns: 1031 Successful response 1032 """ 1033 query: dict[str, object] = {} 1034 if team is not None: 1035 query["team"] = team 1036 if user is not None: 1037 query["user"] = user 1038 if agent is not None: 1039 query["agent"] = agent 1040 if org is not None: 1041 query["org"] = org 1042 if limit is not None: 1043 query["limit"] = limit 1044 if after_cursor is not None: 1045 query["after_cursor"] = after_cursor 1046 return await self._http.request( 1047 f"/api/v1/tasks/{task}/blockers", 1048 query=query, 1049 response_type=BlockerListResponse, 1050 )
List a task's blockers Returns a bounded page of the tasks currently marked as blocking the specified task, newest first. Blocking is informational: a blocked task can still change status, and it stops counting as blocked as soon as every blocker is done. The task's owner is resolved from the task itself.
Arguments:
- task: Blocked task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum blockers to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
async def
create( self, task: str, input: BlockerCreateInput) -> archastro.platform.types.tasks.Task:
1052 async def create(self, task: str, input: BlockerCreateInput) -> Task: 1053 """ 1054 Mark a task as blocked by another task 1055 Records that the task in `blocker` blocks the specified task and returns 1056 the updated task. Blocking is informational the blocked task can still 1057 change status and derived at read time, so the task stops reporting 1058 `is_blocked` as soon as every blocker is done. The blocker must belong to 1059 the same owner (team or user) as the task; self-blocking and blocking a 1060 task that already blocks the blocker (a direct cycle) are rejected. 1061 1062 Args: 1063 task: Blocked task ID (`tsk_...`). 1064 input: Request body. 1065 input.agent: Explicit owning agent (`agi_...`) for privileged calls. 1066 input.blocker: ID of the task that blocks this task (`tsk_...`). 1067 input.org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1068 input.team: Explicit owning team (`tem_...`) for privileged calls. 1069 input.user: Explicit owning user (`usr_...`) for privileged calls. 1070 1071 Returns: 1072 The updated (blocked) task. 1073 """ 1074 return await self._http.request( 1075 f"/api/v1/tasks/{task}/blockers", 1076 method="POST", 1077 body=input, 1078 response_type=Task, 1079 )
Mark a task as blocked by another task
Records that the task in blocker blocks the specified task and returns
the updated task. Blocking is informational the blocked task can still
change status and derived at read time, so the task stops reporting
is_blocked as soon as every blocker is done. The blocker must belong to
the same owner (team or user) as the task; self-blocking and blocking a
task that already blocks the blocker (a direct cycle) are rejected.
Arguments:
- task: Blocked task ID (
tsk_...). - input: Request body.
- input.agent: Explicit owning agent (
agi_...) for privileged calls. - input.blocker: ID of the task that blocks this task (
tsk_...). - input.org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - input.team: Explicit owning team (
tem_...) for privileged calls. - input.user: Explicit owning user (
usr_...) for privileged calls.
Returns:
The updated (blocked) task.
async def
delete(self, task: str, blocker: str) -> None:
1081 async def delete(self, task: str, blocker: str) -> None: 1082 """ 1083 Remove a blocker from a task 1084 Removes the blocking relationship between the task in `blocker` and the 1085 specified task. Returns 204 No Content on success, or 404 if the given 1086 task is not currently marked as blocking this task. 1087 1088 Args: 1089 task: Blocked task ID (`tsk_...`). 1090 blocker: ID of the blocking task to remove (`tsk_...`). 1091 1092 Returns: 1093 Empty response body. HTTP 204 No Content on success. 1094 """ 1095 await self._http.request(f"/api/v1/tasks/{task}/blockers/{blocker}", method="DELETE")
Remove a blocker from a task
Removes the blocking relationship between the task in blocker and the
specified task. Returns 204 No Content on success, or 404 if the given
task is not currently marked as blocking this task.
Arguments:
- task: Blocked task ID (
tsk_...). - blocker: ID of the blocking task to remove (
tsk_...).
Returns:
Empty response body. HTTP 204 No Content on success.
class
AsyncCommentResource:
1098class AsyncCommentResource: 1099 def __init__(self, http: HttpClient): 1100 self._http = http 1101 1102 async def list( 1103 self, 1104 task: str, 1105 *, 1106 team: str | None = None, 1107 user: str | None = None, 1108 agent: str | None = None, 1109 org: str | None = None, 1110 limit: int | None = None, 1111 after_cursor: str | None = None, 1112 ) -> CommentListResponse: 1113 """ 1114 List comments on a task 1115 Returns a bounded page of comments on the specified task, ordered by creation 1116 time ascending. App-scoped developer and server-to-server callers explicitly 1117 provide the owning `team`, `user`, or `agent` and `org`. 1118 1119 Args: 1120 task: Task ID (`tsk_...`). 1121 team: Explicit owning team (`tem_...`) for privileged calls. 1122 user: Explicit owning user (`usr_...`) for privileged calls. 1123 agent: Explicit owning agent (`agi_...`) for privileged calls. 1124 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1125 limit: Maximum comments to return. Capped at 100. 1126 after_cursor: Opaque cursor returned by the previous page. 1127 1128 Returns: 1129 Successful response 1130 """ 1131 query: dict[str, object] = {} 1132 if team is not None: 1133 query["team"] = team 1134 if user is not None: 1135 query["user"] = user 1136 if agent is not None: 1137 query["agent"] = agent 1138 if org is not None: 1139 query["org"] = org 1140 if limit is not None: 1141 query["limit"] = limit 1142 if after_cursor is not None: 1143 query["after_cursor"] = after_cursor 1144 return await self._http.request( 1145 f"/api/v1/tasks/{task}/comments", 1146 query=query, 1147 response_type=CommentListResponse, 1148 ) 1149 1150 async def create(self, task: str, input: CommentCreateInput) -> TaskComment: 1151 """ 1152 Create a comment on a task 1153 Posts a new comment on the specified task and returns the created comment. 1154 The task's owner is resolved from the task itself. 1155 1156 Args: 1157 task: Task ID (`tsk_...`). 1158 input: Request body. 1159 input.comment: Parameters for the comment to create, including its body. 1160 1161 Returns: 1162 The newly created comment. 1163 """ 1164 return await self._http.request( 1165 f"/api/v1/tasks/{task}/comments", 1166 method="POST", 1167 body=input, 1168 response_type=TaskComment, 1169 ) 1170 1171 async def delete(self, task: str, comment: str) -> None: 1172 """ 1173 Delete a task comment 1174 Permanently removes a comment from its task. This action cannot be undone. 1175 The task's owner is resolved from the task itself. 1176 Only the comment's author, an admin of the comment's organization, or an 1177 admin of the owning team may delete a comment. Returns `403 Forbidden` 1178 otherwise. 1179 1180 Args: 1181 task: Task ID (`tsk_...`). 1182 comment: Comment ID (`tcm_...`). 1183 1184 Returns: 1185 Empty body. The server responds with HTTP 204 No Content on success. 1186 """ 1187 await self._http.request(f"/api/v1/tasks/{task}/comments/{comment}", method="DELETE") 1188 1189 async def replace(self, task: str, comment: str, input: CommentReplaceInput) -> TaskComment: 1190 """ 1191 Update a task comment 1192 Replaces the body of an existing comment and returns the updated comment. 1193 The task's owner is resolved from the task itself. 1194 Only the comment's author, an admin of the comment's organization, or an 1195 admin of the owning team may edit a comment. Returns `403 Forbidden` 1196 otherwise. 1197 1198 Args: 1199 task: Task ID (`tsk_...`). 1200 comment: Comment ID (`tcm_...`). 1201 input: Request body. 1202 input.body: Replacement body for the comment. Must be non-empty. 1203 1204 Returns: 1205 The updated comment. 1206 """ 1207 return await self._http.request( 1208 f"/api/v1/tasks/{task}/comments/{comment}", 1209 method="PUT", 1210 body=input, 1211 response_type=TaskComment, 1212 )
AsyncCommentResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> CommentListResponse:
1102 async def list( 1103 self, 1104 task: str, 1105 *, 1106 team: str | None = None, 1107 user: str | None = None, 1108 agent: str | None = None, 1109 org: str | None = None, 1110 limit: int | None = None, 1111 after_cursor: str | None = None, 1112 ) -> CommentListResponse: 1113 """ 1114 List comments on a task 1115 Returns a bounded page of comments on the specified task, ordered by creation 1116 time ascending. App-scoped developer and server-to-server callers explicitly 1117 provide the owning `team`, `user`, or `agent` and `org`. 1118 1119 Args: 1120 task: Task ID (`tsk_...`). 1121 team: Explicit owning team (`tem_...`) for privileged calls. 1122 user: Explicit owning user (`usr_...`) for privileged calls. 1123 agent: Explicit owning agent (`agi_...`) for privileged calls. 1124 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1125 limit: Maximum comments to return. Capped at 100. 1126 after_cursor: Opaque cursor returned by the previous page. 1127 1128 Returns: 1129 Successful response 1130 """ 1131 query: dict[str, object] = {} 1132 if team is not None: 1133 query["team"] = team 1134 if user is not None: 1135 query["user"] = user 1136 if agent is not None: 1137 query["agent"] = agent 1138 if org is not None: 1139 query["org"] = org 1140 if limit is not None: 1141 query["limit"] = limit 1142 if after_cursor is not None: 1143 query["after_cursor"] = after_cursor 1144 return await self._http.request( 1145 f"/api/v1/tasks/{task}/comments", 1146 query=query, 1147 response_type=CommentListResponse, 1148 )
List comments on a task
Returns a bounded page of comments on the specified task, ordered by creation
time ascending. App-scoped developer and server-to-server callers explicitly
provide the owning team, user, or agent and org.
Arguments:
- task: Task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum comments to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
async def
create( self, task: str, input: CommentCreateInput) -> archastro.platform.types.tasks.TaskComment:
1150 async def create(self, task: str, input: CommentCreateInput) -> TaskComment: 1151 """ 1152 Create a comment on a task 1153 Posts a new comment on the specified task and returns the created comment. 1154 The task's owner is resolved from the task itself. 1155 1156 Args: 1157 task: Task ID (`tsk_...`). 1158 input: Request body. 1159 input.comment: Parameters for the comment to create, including its body. 1160 1161 Returns: 1162 The newly created comment. 1163 """ 1164 return await self._http.request( 1165 f"/api/v1/tasks/{task}/comments", 1166 method="POST", 1167 body=input, 1168 response_type=TaskComment, 1169 )
Create a comment on a task Posts a new comment on the specified task and returns the created comment. The task's owner is resolved from the task itself.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.comment: Parameters for the comment to create, including its body.
Returns:
The newly created comment.
async def
delete(self, task: str, comment: str) -> None:
1171 async def delete(self, task: str, comment: str) -> None: 1172 """ 1173 Delete a task comment 1174 Permanently removes a comment from its task. This action cannot be undone. 1175 The task's owner is resolved from the task itself. 1176 Only the comment's author, an admin of the comment's organization, or an 1177 admin of the owning team may delete a comment. Returns `403 Forbidden` 1178 otherwise. 1179 1180 Args: 1181 task: Task ID (`tsk_...`). 1182 comment: Comment ID (`tcm_...`). 1183 1184 Returns: 1185 Empty body. The server responds with HTTP 204 No Content on success. 1186 """ 1187 await self._http.request(f"/api/v1/tasks/{task}/comments/{comment}", method="DELETE")
Delete a task comment
Permanently removes a comment from its task. This action cannot be undone.
The task's owner is resolved from the task itself.
Only the comment's author, an admin of the comment's organization, or an
admin of the owning team may delete a comment. Returns 403 Forbidden
otherwise.
Arguments:
- task: Task ID (
tsk_...). - comment: Comment ID (
tcm_...).
Returns:
Empty body. The server responds with HTTP 204 No Content on success.
async def
replace( self, task: str, comment: str, input: CommentReplaceInput) -> archastro.platform.types.tasks.TaskComment:
1189 async def replace(self, task: str, comment: str, input: CommentReplaceInput) -> TaskComment: 1190 """ 1191 Update a task comment 1192 Replaces the body of an existing comment and returns the updated comment. 1193 The task's owner is resolved from the task itself. 1194 Only the comment's author, an admin of the comment's organization, or an 1195 admin of the owning team may edit a comment. Returns `403 Forbidden` 1196 otherwise. 1197 1198 Args: 1199 task: Task ID (`tsk_...`). 1200 comment: Comment ID (`tcm_...`). 1201 input: Request body. 1202 input.body: Replacement body for the comment. Must be non-empty. 1203 1204 Returns: 1205 The updated comment. 1206 """ 1207 return await self._http.request( 1208 f"/api/v1/tasks/{task}/comments/{comment}", 1209 method="PUT", 1210 body=input, 1211 response_type=TaskComment, 1212 )
Update a task comment
Replaces the body of an existing comment and returns the updated comment.
The task's owner is resolved from the task itself.
Only the comment's author, an admin of the comment's organization, or an
admin of the owning team may edit a comment. Returns 403 Forbidden
otherwise.
Arguments:
- task: Task ID (
tsk_...). - comment: Comment ID (
tcm_...). - input: Request body.
- input.body: Replacement body for the comment. Must be non-empty.
Returns:
The updated comment.
class
AsyncLeaseResource:
1215class AsyncLeaseResource: 1216 def __init__(self, http: HttpClient): 1217 self._http = http 1218 1219 async def remove(self, task: str) -> None: 1220 """ 1221 Release a task session lease 1222 Releases the authenticated assignee's matching live task lease. Repeating a 1223 release after the lease is absent succeeds. A different live successor lease 1224 returns a mismatch. 1225 1226 Args: 1227 task: Task ID (`tsk_...`). 1228 1229 Returns: 1230 Empty response. HTTP 204 is returned after release is accepted. 1231 """ 1232 await self._http.request(f"/api/v1/tasks/{task}/lease", method="DELETE") 1233 1234 async def list(self, task: str) -> TaskSessionLeaseSummary | None: 1235 """ 1236 Retrieve a task's current session lease 1237 Returns the authenticated assignee's viewer-safe live lease summary, or null 1238 when no live lease exists. Fencing and opaque session identifiers are never 1239 included. 1240 1241 Args: 1242 task: Task ID (`tsk_...`). 1243 1244 Returns: 1245 Viewer-safe live lease summary, or null. 1246 """ 1247 return await self._http.request( 1248 f"/api/v1/tasks/{task}/lease", 1249 response_type=TaskSessionLeaseSummary | None, 1250 ) 1251 1252 async def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: 1253 """ 1254 Claim a task for a coding session 1255 Atomically claims a user-assigned task for the authenticated user's coding 1256 session. The caller generates and retains both UUIDs. An exact retry returns 1257 the existing lease without extending it; another live holder produces a 1258 conflict. Developer and server-to-server credentials cannot impersonate the 1259 assigned user. 1260 1261 Args: 1262 task: Task ID (`tsk_...`). 1263 input: Request body. 1264 input.harness: Bounded harness identifier. 1265 input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. 1266 input.lease_id: Caller-generated lease UUID. 1267 input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. 1268 input.session_id: Caller-generated coding-session UUID. 1269 input.session_name: Human-readable coding-session label. 1270 1271 Returns: 1272 The caller-held lease, including its fencing token. 1273 """ 1274 return await self._http.request( 1275 f"/api/v1/tasks/{task}/lease", 1276 method="POST", 1277 body=input, 1278 response_type=TaskSessionLease, 1279 ) 1280 1281 async def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: 1282 """ 1283 Renew a task session lease 1284 Renews the authenticated assignee's matching live task lease. Both 1285 caller-generated UUIDs must match the aggregate's current lease. 1286 1287 Args: 1288 task: Task ID (`tsk_...`). 1289 input: Request body. 1290 input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds. 1291 input.lease_id: Current caller-held lease UUID. 1292 input.session_id: Current coding-session UUID. 1293 1294 Returns: 1295 The renewed caller-held lease. 1296 """ 1297 return await self._http.request( 1298 f"/api/v1/tasks/{task}/lease/renew", 1299 method="POST", 1300 body=input, 1301 response_type=TaskSessionLease, 1302 )
AsyncLeaseResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
remove(self, task: str) -> None:
1219 async def remove(self, task: str) -> None: 1220 """ 1221 Release a task session lease 1222 Releases the authenticated assignee's matching live task lease. Repeating a 1223 release after the lease is absent succeeds. A different live successor lease 1224 returns a mismatch. 1225 1226 Args: 1227 task: Task ID (`tsk_...`). 1228 1229 Returns: 1230 Empty response. HTTP 204 is returned after release is accepted. 1231 """ 1232 await self._http.request(f"/api/v1/tasks/{task}/lease", method="DELETE")
Release a task session lease Releases the authenticated assignee's matching live task lease. Repeating a release after the lease is absent succeeds. A different live successor lease returns a mismatch.
Arguments:
- task: Task ID (
tsk_...).
Returns:
Empty response. HTTP 204 is returned after release is accepted.
1234 async def list(self, task: str) -> TaskSessionLeaseSummary | None: 1235 """ 1236 Retrieve a task's current session lease 1237 Returns the authenticated assignee's viewer-safe live lease summary, or null 1238 when no live lease exists. Fencing and opaque session identifiers are never 1239 included. 1240 1241 Args: 1242 task: Task ID (`tsk_...`). 1243 1244 Returns: 1245 Viewer-safe live lease summary, or null. 1246 """ 1247 return await self._http.request( 1248 f"/api/v1/tasks/{task}/lease", 1249 response_type=TaskSessionLeaseSummary | None, 1250 )
Retrieve a task's current session lease Returns the authenticated assignee's viewer-safe live lease summary, or null when no live lease exists. Fencing and opaque session identifiers are never included.
Arguments:
- task: Task ID (
tsk_...).
Returns:
Viewer-safe live lease summary, or null.
async def
create( self, task: str, input: LeaseCreateInput) -> archastro.platform.types.tasks.TaskSessionLease:
1252 async def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: 1253 """ 1254 Claim a task for a coding session 1255 Atomically claims a user-assigned task for the authenticated user's coding 1256 session. The caller generates and retains both UUIDs. An exact retry returns 1257 the existing lease without extending it; another live holder produces a 1258 conflict. Developer and server-to-server credentials cannot impersonate the 1259 assigned user. 1260 1261 Args: 1262 task: Task ID (`tsk_...`). 1263 input: Request body. 1264 input.harness: Bounded harness identifier. 1265 input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. 1266 input.lease_id: Caller-generated lease UUID. 1267 input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. 1268 input.session_id: Caller-generated coding-session UUID. 1269 input.session_name: Human-readable coding-session label. 1270 1271 Returns: 1272 The caller-held lease, including its fencing token. 1273 """ 1274 return await self._http.request( 1275 f"/api/v1/tasks/{task}/lease", 1276 method="POST", 1277 body=input, 1278 response_type=TaskSessionLease, 1279 )
Claim a task for a coding session Atomically claims a user-assigned task for the authenticated user's coding session. The caller generates and retains both UUIDs. An exact retry returns the existing lease without extending it; another live holder produces a conflict. Developer and server-to-server credentials cannot impersonate the assigned user.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.harness: Bounded harness identifier.
- input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds.
- input.lease_id: Caller-generated lease UUID.
- input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers.
- input.session_id: Caller-generated coding-session UUID.
- input.session_name: Human-readable coding-session label.
Returns:
The caller-held lease, including its fencing token.
async def
renew( self, task: str, input: LeaseRenewInput) -> archastro.platform.types.tasks.TaskSessionLease:
1281 async def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: 1282 """ 1283 Renew a task session lease 1284 Renews the authenticated assignee's matching live task lease. Both 1285 caller-generated UUIDs must match the aggregate's current lease. 1286 1287 Args: 1288 task: Task ID (`tsk_...`). 1289 input: Request body. 1290 input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds. 1291 input.lease_id: Current caller-held lease UUID. 1292 input.session_id: Current coding-session UUID. 1293 1294 Returns: 1295 The renewed caller-held lease. 1296 """ 1297 return await self._http.request( 1298 f"/api/v1/tasks/{task}/lease/renew", 1299 method="POST", 1300 body=input, 1301 response_type=TaskSessionLease, 1302 )
Renew a task session lease Renews the authenticated assignee's matching live task lease. Both caller-generated UUIDs must match the aggregate's current lease.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds.
- input.lease_id: Current caller-held lease UUID.
- input.session_id: Current coding-session UUID.
Returns:
The renewed caller-held lease.
class
AsyncLinkResource:
1305class AsyncLinkResource: 1306 def __init__(self, http: HttpClient): 1307 self._http = http 1308 1309 async def remove(self, task: str) -> None: 1310 """ 1311 Remove an external link from a task 1312 1313 Args: 1314 task: Task ID (`tsk_...`). 1315 1316 Returns: 1317 HTTP 204 on success. 1318 """ 1319 await self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE") 1320 1321 async def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: 1322 """ 1323 Add an external link to a task 1324 1325 Args: 1326 task: Task ID (`tsk_...`). 1327 input: Request body. 1328 input.external_scope: External container ID. 1329 input.object_id: External object ID. 1330 input.object_type: External object type. 1331 1332 Returns: 1333 The created external link. 1334 """ 1335 return await self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input)
AsyncLinkResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
remove(self, task: str) -> None:
1309 async def remove(self, task: str) -> None: 1310 """ 1311 Remove an external link from a task 1312 1313 Args: 1314 task: Task ID (`tsk_...`). 1315 1316 Returns: 1317 HTTP 204 on success. 1318 """ 1319 await self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE")
Remove an external link from a task
Arguments:
- task: Task ID (
tsk_...).
Returns:
HTTP 204 on success.
1321 async def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: 1322 """ 1323 Add an external link to a task 1324 1325 Args: 1326 task: Task ID (`tsk_...`). 1327 input: Request body. 1328 input.external_scope: External container ID. 1329 input.object_id: External object ID. 1330 input.object_type: External object type. 1331 1332 Returns: 1333 The created external link. 1334 """ 1335 return await self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input)
Add an external link to a task
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.external_scope: External container ID.
- input.object_id: External object ID.
- input.object_type: External object type.
Returns:
The created external link.
class
AsyncTaskResource:
1338class AsyncTaskResource: 1339 def __init__(self, http: HttpClient): 1340 self._http = http 1341 self.blockers = AsyncBlockerResource(http) 1342 self.comments = AsyncCommentResource(http) 1343 self.lease = AsyncLeaseResource(http) 1344 self.links = AsyncLinkResource(http) 1345 1346 async def delete(self, task: str) -> None: 1347 """ 1348 Delete a task 1349 Deletes a task from task lists and detail views. The task event stream is 1350 retained for auditability, while comments are removed and direct subtasks 1351 are promoted to top-level tasks. 1352 The delete event is accepted before the read model is updated. Clients 1353 should remove the task from local collections immediately; subsequent reads 1354 converge once the projection processes the event. 1355 Authenticated users may delete tasks they can access using their session 1356 identity. App-scoped developer and server-to-server callers must explicitly 1357 supply the task's `org` and owner. `team` or `user` identifies that owner; 1358 when neither is present, `agent` identifies an agent-owned task. With a team 1359 or user owner, `agent` identifies the acting principal. Each reference is 1360 validated before deletion. 1361 1362 Args: 1363 task: Task ID (`tsk_...`). 1364 1365 Returns: 1366 Empty response. HTTP 204 is returned after the delete event is accepted. 1367 """ 1368 await self._http.request(f"/api/v1/tasks/{task}", method="DELETE") 1369 1370 async def get( 1371 self, 1372 task: str, 1373 *, 1374 team: str | None = None, 1375 user: str | None = None, 1376 agent: str | None = None, 1377 org: str | None = None, 1378 ) -> Task: 1379 """ 1380 Retrieve a task 1381 Returns the full task object for the specified task ID. Authenticated users 1382 and agents resolve access through their session. App-scoped developer and 1383 server-to-server callers explicitly provide the owning `team`, `user`, or `agent` and 1384 `org`. Callers without access receive a 404. 1385 1386 Args: 1387 task: Task ID (`tsk_...`). 1388 team: Explicit owning team (`tem_...`) for privileged calls. 1389 user: Explicit owning user (`usr_...`) for privileged calls. 1390 agent: Explicit owning agent (`agi_...`) for privileged calls. 1391 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1392 1393 Returns: 1394 The requested task. 1395 """ 1396 query: dict[str, object] = {} 1397 if team is not None: 1398 query["team"] = team 1399 if user is not None: 1400 query["user"] = user 1401 if agent is not None: 1402 query["agent"] = agent 1403 if org is not None: 1404 query["org"] = org 1405 return await self._http.request(f"/api/v1/tasks/{task}", query=query, response_type=Task) 1406 1407 async def replace(self, task: str, input: TaskReplaceInput) -> Task: 1408 """ 1409 Update a task 1410 Updates the supplied fields on a task and returns the complete updated task. 1411 Authenticated users use their session identity. App-scoped developer and 1412 server-to-server callers must explicitly supply the task's `org` and owner. 1413 `team` or `user` identifies that owner; when neither is present, `agent` 1414 identifies an agent-owned task. With a team or user owner, `agent` identifies 1415 the acting principal. Every reference is validated before the update. 1416 A cooperating coding-session client may supply both `lease_id` and 1417 `lease_session_id`. The task aggregate fences that update against the live 1418 lease and records server-sourced session provenance. Omitting both remains a 1419 normal authorized human/API update. 1420 1421 Args: 1422 task: Task ID (`tsk_...`). 1423 input: Request body. 1424 input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. 1425 input.description: Updated long-form description. 1426 input.due_date: Updated due date in ISO 8601 format, or null to clear it. 1427 input.epic: Replacement grouping label. Pass null to clear it. 1428 input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. 1429 input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. 1430 input.links: Replacement related-links object. 1431 input.metadata: Replacement task metadata object. 1432 input.name: Updated display name for the task. 1433 input.org: Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization. 1434 input.owner_agent: Assign to an agent by public ID (`agi_...`). 1435 input.owner_user: Assign to a user by public ID (`usr_...`). 1436 input.parent: 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. 1437 input.priority: Updated priority from 0 (highest) to 4 (lowest). 1438 input.source_id: Replacement source object identity. Must be supplied with the other source fields. 1439 input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. 1440 input.source_type: Replacement source object kind. Must be supplied with the other source fields. 1441 input.status: Updated status: `open`, `in_progress`, or `done`. 1442 input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. 1443 input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. 1444 input.user: Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member. 1445 1446 Returns: 1447 The updated task. 1448 """ 1449 return await self._http.request( 1450 f"/api/v1/tasks/{task}", 1451 method="PUT", 1452 body=input, 1453 response_type=Task, 1454 ) 1455 1456 async def activity( 1457 self, 1458 task: str, 1459 *, 1460 team: str | None = None, 1461 user: str | None = None, 1462 agent: str | None = None, 1463 org: str | None = None, 1464 limit: int | None = None, 1465 after_cursor: str | None = None, 1466 ) -> TaskActivityResponse: 1467 """ 1468 List a task's activity 1469 Returns a bounded chronological page of activity for the specified task. 1470 App-scoped developer and server-to-server callers explicitly provide the 1471 owning `team`, `user`, or `agent` and `org`. 1472 1473 Args: 1474 task: Task ID (`tsk_...`). 1475 team: Explicit owning team (`tem_...`) for privileged calls. 1476 user: Explicit owning user (`usr_...`) for privileged calls. 1477 agent: Explicit owning agent (`agi_...`) for privileged calls. 1478 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1479 limit: Maximum entries to return. Capped at 100. 1480 after_cursor: Opaque cursor returned by the previous page. 1481 1482 Returns: 1483 Successful response 1484 """ 1485 query: dict[str, object] = {} 1486 if team is not None: 1487 query["team"] = team 1488 if user is not None: 1489 query["user"] = user 1490 if agent is not None: 1491 query["agent"] = agent 1492 if org is not None: 1493 query["org"] = org 1494 if limit is not None: 1495 query["limit"] = limit 1496 if after_cursor is not None: 1497 query["after_cursor"] = after_cursor 1498 return await self._http.request( 1499 f"/api/v1/tasks/{task}/activity", 1500 query=query, 1501 response_type=TaskActivityResponse, 1502 ) 1503 1504 async def blocking( 1505 self, 1506 task: str, 1507 *, 1508 team: str | None = None, 1509 user: str | None = None, 1510 agent: str | None = None, 1511 org: str | None = None, 1512 limit: int | None = None, 1513 after_cursor: str | None = None, 1514 ) -> TaskBlockingResponse: 1515 """ 1516 List the tasks a task blocks 1517 Returns a bounded page of the tasks that the specified task is marked as 1518 blocking (the inverse of `GET /tasks/{task}/blockers`), newest first. 1519 The task's owner is resolved from the task itself. 1520 1521 Args: 1522 task: Blocking task ID (`tsk_...`). 1523 team: Explicit owning team (`tem_...`) for privileged calls. 1524 user: Explicit owning user (`usr_...`) for privileged calls. 1525 agent: Explicit owning agent (`agi_...`) for privileged calls. 1526 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1527 limit: Maximum tasks to return. Capped at 100. 1528 after_cursor: Opaque cursor returned by the previous page. 1529 1530 Returns: 1531 Successful response 1532 """ 1533 query: dict[str, object] = {} 1534 if team is not None: 1535 query["team"] = team 1536 if user is not None: 1537 query["user"] = user 1538 if agent is not None: 1539 query["agent"] = agent 1540 if org is not None: 1541 query["org"] = org 1542 if limit is not None: 1543 query["limit"] = limit 1544 if after_cursor is not None: 1545 query["after_cursor"] = after_cursor 1546 return await self._http.request( 1547 f"/api/v1/tasks/{task}/blocking", 1548 query=query, 1549 response_type=TaskBlockingResponse, 1550 ) 1551 1552 async def subtasks( 1553 self, 1554 task: str, 1555 *, 1556 team: str | None = None, 1557 user: str | None = None, 1558 agent: str | None = None, 1559 org: str | None = None, 1560 limit: int | None = None, 1561 after_cursor: str | None = None, 1562 ) -> TaskSubtasksResponse: 1563 """ 1564 List a task's subtasks 1565 Returns a bounded page of the specified task's subtasks (tasks whose 1566 `parent` is this task), newest first. Subtasks nest exactly one level, so 1567 entries never have subtasks of their own. Privileged callers explicitly 1568 provide the owning `team`, `user`, or `agent` and `org`. 1569 1570 Args: 1571 task: Parent task ID (`tsk_...`). 1572 team: Explicit owning team (`tem_...`) for privileged calls. 1573 user: Explicit owning user (`usr_...`) for privileged calls. 1574 agent: Explicit owning agent (`agi_...`) for privileged calls. 1575 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1576 limit: Maximum subtasks to return. Capped at 100. 1577 after_cursor: Opaque cursor returned by the previous page. 1578 1579 Returns: 1580 Successful response 1581 """ 1582 query: dict[str, object] = {} 1583 if team is not None: 1584 query["team"] = team 1585 if user is not None: 1586 query["user"] = user 1587 if agent is not None: 1588 query["agent"] = agent 1589 if org is not None: 1590 query["org"] = org 1591 if limit is not None: 1592 query["limit"] = limit 1593 if after_cursor is not None: 1594 query["after_cursor"] = after_cursor 1595 return await self._http.request( 1596 f"/api/v1/tasks/{task}/subtasks", 1597 query=query, 1598 response_type=TaskSubtasksResponse, 1599 )
AsyncTaskResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
delete(self, task: str) -> None:
1346 async def delete(self, task: str) -> None: 1347 """ 1348 Delete a task 1349 Deletes a task from task lists and detail views. The task event stream is 1350 retained for auditability, while comments are removed and direct subtasks 1351 are promoted to top-level tasks. 1352 The delete event is accepted before the read model is updated. Clients 1353 should remove the task from local collections immediately; subsequent reads 1354 converge once the projection processes the event. 1355 Authenticated users may delete tasks they can access using their session 1356 identity. App-scoped developer and server-to-server callers must explicitly 1357 supply the task's `org` and owner. `team` or `user` identifies that owner; 1358 when neither is present, `agent` identifies an agent-owned task. With a team 1359 or user owner, `agent` identifies the acting principal. Each reference is 1360 validated before deletion. 1361 1362 Args: 1363 task: Task ID (`tsk_...`). 1364 1365 Returns: 1366 Empty response. HTTP 204 is returned after the delete event is accepted. 1367 """ 1368 await self._http.request(f"/api/v1/tasks/{task}", method="DELETE")
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.
Arguments:
- task: Task ID (
tsk_...).
Returns:
Empty response. HTTP 204 is returned after the delete event is accepted.
async def
get( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None) -> archastro.platform.types.tasks.Task:
1370 async def get( 1371 self, 1372 task: str, 1373 *, 1374 team: str | None = None, 1375 user: str | None = None, 1376 agent: str | None = None, 1377 org: str | None = None, 1378 ) -> Task: 1379 """ 1380 Retrieve a task 1381 Returns the full task object for the specified task ID. Authenticated users 1382 and agents resolve access through their session. App-scoped developer and 1383 server-to-server callers explicitly provide the owning `team`, `user`, or `agent` and 1384 `org`. Callers without access receive a 404. 1385 1386 Args: 1387 task: Task ID (`tsk_...`). 1388 team: Explicit owning team (`tem_...`) for privileged calls. 1389 user: Explicit owning user (`usr_...`) for privileged calls. 1390 agent: Explicit owning agent (`agi_...`) for privileged calls. 1391 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1392 1393 Returns: 1394 The requested task. 1395 """ 1396 query: dict[str, object] = {} 1397 if team is not None: 1398 query["team"] = team 1399 if user is not None: 1400 query["user"] = user 1401 if agent is not None: 1402 query["agent"] = agent 1403 if org is not None: 1404 query["org"] = org 1405 return await self._http.request(f"/api/v1/tasks/{task}", query=query, response_type=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.
Arguments:
- task: Task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped.
Returns:
The requested task.
async def
replace( self, task: str, input: TaskReplaceInput) -> archastro.platform.types.tasks.Task:
1407 async def replace(self, task: str, input: TaskReplaceInput) -> Task: 1408 """ 1409 Update a task 1410 Updates the supplied fields on a task and returns the complete updated task. 1411 Authenticated users use their session identity. App-scoped developer and 1412 server-to-server callers must explicitly supply the task's `org` and owner. 1413 `team` or `user` identifies that owner; when neither is present, `agent` 1414 identifies an agent-owned task. With a team or user owner, `agent` identifies 1415 the acting principal. Every reference is validated before the update. 1416 A cooperating coding-session client may supply both `lease_id` and 1417 `lease_session_id`. The task aggregate fences that update against the live 1418 lease and records server-sourced session provenance. Omitting both remains a 1419 normal authorized human/API update. 1420 1421 Args: 1422 task: Task ID (`tsk_...`). 1423 input: Request body. 1424 input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. 1425 input.description: Updated long-form description. 1426 input.due_date: Updated due date in ISO 8601 format, or null to clear it. 1427 input.epic: Replacement grouping label. Pass null to clear it. 1428 input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. 1429 input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. 1430 input.links: Replacement related-links object. 1431 input.metadata: Replacement task metadata object. 1432 input.name: Updated display name for the task. 1433 input.org: Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization. 1434 input.owner_agent: Assign to an agent by public ID (`agi_...`). 1435 input.owner_user: Assign to a user by public ID (`usr_...`). 1436 input.parent: 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. 1437 input.priority: Updated priority from 0 (highest) to 4 (lowest). 1438 input.source_id: Replacement source object identity. Must be supplied with the other source fields. 1439 input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. 1440 input.source_type: Replacement source object kind. Must be supplied with the other source fields. 1441 input.status: Updated status: `open`, `in_progress`, or `done`. 1442 input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. 1443 input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. 1444 input.user: Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member. 1445 1446 Returns: 1447 The updated task. 1448 """ 1449 return await self._http.request( 1450 f"/api/v1/tasks/{task}", 1451 method="PUT", 1452 body=input, 1453 response_type=Task, 1454 )
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.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.agent: Explicit agent (
agi_...). It is the owner whenteamanduserare absent; otherwise it is the acting principal. - input.description: Updated long-form description.
- input.due_date: Updated due date in ISO 8601 format, or null to clear it.
- input.epic: Replacement grouping label. Pass null to clear it.
- input.lease_id: Current caller-held lease UUID. Must be paired with
lease_session_id. - input.lease_session_id: Current coding-session UUID. Must be paired with
lease_id. - input.links: Replacement related-links object.
- input.metadata: Replacement task metadata object.
- input.name: Updated display name for the task.
- input.org: Explicit organization (
org_...) for a developer or server-to-server call. Pass null for an owner outside an organization. - input.owner_agent: Assign to an agent by public ID (
agi_...). - input.owner_user: Assign to a user by public ID (
usr_...). - input.parent: 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. - input.priority: Updated priority from 0 (highest) to 4 (lowest).
- input.source_id: Replacement source object identity. Must be supplied with the other source fields.
- input.source_scope: Replacement source container. Pass together with
source_typeandsource_id, or pass all three as null to clear the source. - input.source_type: Replacement source object kind. Must be supplied with the other source fields.
- input.status: Updated status:
open,in_progress, ordone. - input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags.
- input.team: Explicit owning team (
tem_...) for a developer or server-to-server call. - input.user: Explicit user (
usr_...) for a developer or server-to-server call. Withteam, this identifies the acting team member.
Returns:
The updated task.
async def
activity( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> TaskActivityResponse:
1456 async def activity( 1457 self, 1458 task: str, 1459 *, 1460 team: str | None = None, 1461 user: str | None = None, 1462 agent: str | None = None, 1463 org: str | None = None, 1464 limit: int | None = None, 1465 after_cursor: str | None = None, 1466 ) -> TaskActivityResponse: 1467 """ 1468 List a task's activity 1469 Returns a bounded chronological page of activity for the specified task. 1470 App-scoped developer and server-to-server callers explicitly provide the 1471 owning `team`, `user`, or `agent` and `org`. 1472 1473 Args: 1474 task: Task ID (`tsk_...`). 1475 team: Explicit owning team (`tem_...`) for privileged calls. 1476 user: Explicit owning user (`usr_...`) for privileged calls. 1477 agent: Explicit owning agent (`agi_...`) for privileged calls. 1478 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1479 limit: Maximum entries to return. Capped at 100. 1480 after_cursor: Opaque cursor returned by the previous page. 1481 1482 Returns: 1483 Successful response 1484 """ 1485 query: dict[str, object] = {} 1486 if team is not None: 1487 query["team"] = team 1488 if user is not None: 1489 query["user"] = user 1490 if agent is not None: 1491 query["agent"] = agent 1492 if org is not None: 1493 query["org"] = org 1494 if limit is not None: 1495 query["limit"] = limit 1496 if after_cursor is not None: 1497 query["after_cursor"] = after_cursor 1498 return await self._http.request( 1499 f"/api/v1/tasks/{task}/activity", 1500 query=query, 1501 response_type=TaskActivityResponse, 1502 )
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.
Arguments:
- task: Task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum entries to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
async def
blocking( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> TaskBlockingResponse:
1504 async def blocking( 1505 self, 1506 task: str, 1507 *, 1508 team: str | None = None, 1509 user: str | None = None, 1510 agent: str | None = None, 1511 org: str | None = None, 1512 limit: int | None = None, 1513 after_cursor: str | None = None, 1514 ) -> TaskBlockingResponse: 1515 """ 1516 List the tasks a task blocks 1517 Returns a bounded page of the tasks that the specified task is marked as 1518 blocking (the inverse of `GET /tasks/{task}/blockers`), newest first. 1519 The task's owner is resolved from the task itself. 1520 1521 Args: 1522 task: Blocking task ID (`tsk_...`). 1523 team: Explicit owning team (`tem_...`) for privileged calls. 1524 user: Explicit owning user (`usr_...`) for privileged calls. 1525 agent: Explicit owning agent (`agi_...`) for privileged calls. 1526 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1527 limit: Maximum tasks to return. Capped at 100. 1528 after_cursor: Opaque cursor returned by the previous page. 1529 1530 Returns: 1531 Successful response 1532 """ 1533 query: dict[str, object] = {} 1534 if team is not None: 1535 query["team"] = team 1536 if user is not None: 1537 query["user"] = user 1538 if agent is not None: 1539 query["agent"] = agent 1540 if org is not None: 1541 query["org"] = org 1542 if limit is not None: 1543 query["limit"] = limit 1544 if after_cursor is not None: 1545 query["after_cursor"] = after_cursor 1546 return await self._http.request( 1547 f"/api/v1/tasks/{task}/blocking", 1548 query=query, 1549 response_type=TaskBlockingResponse, 1550 )
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.
Arguments:
- task: Blocking task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
async def
subtasks( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> TaskSubtasksResponse:
1552 async def subtasks( 1553 self, 1554 task: str, 1555 *, 1556 team: str | None = None, 1557 user: str | None = None, 1558 agent: str | None = None, 1559 org: str | None = None, 1560 limit: int | None = None, 1561 after_cursor: str | None = None, 1562 ) -> TaskSubtasksResponse: 1563 """ 1564 List a task's subtasks 1565 Returns a bounded page of the specified task's subtasks (tasks whose 1566 `parent` is this task), newest first. Subtasks nest exactly one level, so 1567 entries never have subtasks of their own. Privileged callers explicitly 1568 provide the owning `team`, `user`, or `agent` and `org`. 1569 1570 Args: 1571 task: Parent task ID (`tsk_...`). 1572 team: Explicit owning team (`tem_...`) for privileged calls. 1573 user: Explicit owning user (`usr_...`) for privileged calls. 1574 agent: Explicit owning agent (`agi_...`) for privileged calls. 1575 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1576 limit: Maximum subtasks to return. Capped at 100. 1577 after_cursor: Opaque cursor returned by the previous page. 1578 1579 Returns: 1580 Successful response 1581 """ 1582 query: dict[str, object] = {} 1583 if team is not None: 1584 query["team"] = team 1585 if user is not None: 1586 query["user"] = user 1587 if agent is not None: 1588 query["agent"] = agent 1589 if org is not None: 1590 query["org"] = org 1591 if limit is not None: 1592 query["limit"] = limit 1593 if after_cursor is not None: 1594 query["after_cursor"] = after_cursor 1595 return await self._http.request( 1596 f"/api/v1/tasks/{task}/subtasks", 1597 query=query, 1598 response_type=TaskSubtasksResponse, 1599 )
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.
Arguments:
- task: Parent task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum subtasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
class
BlockerResource:
1602class BlockerResource: 1603 def __init__(self, http: SyncHttpClient): 1604 self._http = http 1605 1606 def list( 1607 self, 1608 task: str, 1609 *, 1610 team: str | None = None, 1611 user: str | None = None, 1612 agent: str | None = None, 1613 org: str | None = None, 1614 limit: int | None = None, 1615 after_cursor: str | None = None, 1616 ) -> BlockerListResponse: 1617 """ 1618 List a task's blockers 1619 Returns a bounded page of the tasks currently marked as blocking the 1620 specified task, newest first. Blocking is informational: a blocked task 1621 can still change status, and it stops counting as blocked as soon as 1622 every blocker is done. The task's owner is resolved from the task itself. 1623 1624 Args: 1625 task: Blocked task ID (`tsk_...`). 1626 team: Explicit owning team (`tem_...`) for privileged calls. 1627 user: Explicit owning user (`usr_...`) for privileged calls. 1628 agent: Explicit owning agent (`agi_...`) for privileged calls. 1629 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1630 limit: Maximum blockers to return. Capped at 100. 1631 after_cursor: Opaque cursor returned by the previous page. 1632 1633 Returns: 1634 Successful response 1635 """ 1636 query: dict[str, object] = {} 1637 if team is not None: 1638 query["team"] = team 1639 if user is not None: 1640 query["user"] = user 1641 if agent is not None: 1642 query["agent"] = agent 1643 if org is not None: 1644 query["org"] = org 1645 if limit is not None: 1646 query["limit"] = limit 1647 if after_cursor is not None: 1648 query["after_cursor"] = after_cursor 1649 return self._http.request( 1650 f"/api/v1/tasks/{task}/blockers", 1651 query=query, 1652 response_type=BlockerListResponse, 1653 ) 1654 1655 def create(self, task: str, input: BlockerCreateInput) -> Task: 1656 """ 1657 Mark a task as blocked by another task 1658 Records that the task in `blocker` blocks the specified task and returns 1659 the updated task. Blocking is informational the blocked task can still 1660 change status and derived at read time, so the task stops reporting 1661 `is_blocked` as soon as every blocker is done. The blocker must belong to 1662 the same owner (team or user) as the task; self-blocking and blocking a 1663 task that already blocks the blocker (a direct cycle) are rejected. 1664 1665 Args: 1666 task: Blocked task ID (`tsk_...`). 1667 input: Request body. 1668 input.agent: Explicit owning agent (`agi_...`) for privileged calls. 1669 input.blocker: ID of the task that blocks this task (`tsk_...`). 1670 input.org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1671 input.team: Explicit owning team (`tem_...`) for privileged calls. 1672 input.user: Explicit owning user (`usr_...`) for privileged calls. 1673 1674 Returns: 1675 The updated (blocked) task. 1676 """ 1677 return self._http.request( 1678 f"/api/v1/tasks/{task}/blockers", 1679 method="POST", 1680 body=input, 1681 response_type=Task, 1682 ) 1683 1684 def delete(self, task: str, blocker: str) -> None: 1685 """ 1686 Remove a blocker from a task 1687 Removes the blocking relationship between the task in `blocker` and the 1688 specified task. Returns 204 No Content on success, or 404 if the given 1689 task is not currently marked as blocking this task. 1690 1691 Args: 1692 task: Blocked task ID (`tsk_...`). 1693 blocker: ID of the blocking task to remove (`tsk_...`). 1694 1695 Returns: 1696 Empty response body. HTTP 204 No Content on success. 1697 """ 1698 self._http.request(f"/api/v1/tasks/{task}/blockers/{blocker}", method="DELETE")
BlockerResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> BlockerListResponse:
1606 def list( 1607 self, 1608 task: str, 1609 *, 1610 team: str | None = None, 1611 user: str | None = None, 1612 agent: str | None = None, 1613 org: str | None = None, 1614 limit: int | None = None, 1615 after_cursor: str | None = None, 1616 ) -> BlockerListResponse: 1617 """ 1618 List a task's blockers 1619 Returns a bounded page of the tasks currently marked as blocking the 1620 specified task, newest first. Blocking is informational: a blocked task 1621 can still change status, and it stops counting as blocked as soon as 1622 every blocker is done. The task's owner is resolved from the task itself. 1623 1624 Args: 1625 task: Blocked task ID (`tsk_...`). 1626 team: Explicit owning team (`tem_...`) for privileged calls. 1627 user: Explicit owning user (`usr_...`) for privileged calls. 1628 agent: Explicit owning agent (`agi_...`) for privileged calls. 1629 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1630 limit: Maximum blockers to return. Capped at 100. 1631 after_cursor: Opaque cursor returned by the previous page. 1632 1633 Returns: 1634 Successful response 1635 """ 1636 query: dict[str, object] = {} 1637 if team is not None: 1638 query["team"] = team 1639 if user is not None: 1640 query["user"] = user 1641 if agent is not None: 1642 query["agent"] = agent 1643 if org is not None: 1644 query["org"] = org 1645 if limit is not None: 1646 query["limit"] = limit 1647 if after_cursor is not None: 1648 query["after_cursor"] = after_cursor 1649 return self._http.request( 1650 f"/api/v1/tasks/{task}/blockers", 1651 query=query, 1652 response_type=BlockerListResponse, 1653 )
List a task's blockers Returns a bounded page of the tasks currently marked as blocking the specified task, newest first. Blocking is informational: a blocked task can still change status, and it stops counting as blocked as soon as every blocker is done. The task's owner is resolved from the task itself.
Arguments:
- task: Blocked task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum blockers to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
1655 def create(self, task: str, input: BlockerCreateInput) -> Task: 1656 """ 1657 Mark a task as blocked by another task 1658 Records that the task in `blocker` blocks the specified task and returns 1659 the updated task. Blocking is informational the blocked task can still 1660 change status and derived at read time, so the task stops reporting 1661 `is_blocked` as soon as every blocker is done. The blocker must belong to 1662 the same owner (team or user) as the task; self-blocking and blocking a 1663 task that already blocks the blocker (a direct cycle) are rejected. 1664 1665 Args: 1666 task: Blocked task ID (`tsk_...`). 1667 input: Request body. 1668 input.agent: Explicit owning agent (`agi_...`) for privileged calls. 1669 input.blocker: ID of the task that blocks this task (`tsk_...`). 1670 input.org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1671 input.team: Explicit owning team (`tem_...`) for privileged calls. 1672 input.user: Explicit owning user (`usr_...`) for privileged calls. 1673 1674 Returns: 1675 The updated (blocked) task. 1676 """ 1677 return self._http.request( 1678 f"/api/v1/tasks/{task}/blockers", 1679 method="POST", 1680 body=input, 1681 response_type=Task, 1682 )
Mark a task as blocked by another task
Records that the task in blocker blocks the specified task and returns
the updated task. Blocking is informational the blocked task can still
change status and derived at read time, so the task stops reporting
is_blocked as soon as every blocker is done. The blocker must belong to
the same owner (team or user) as the task; self-blocking and blocking a
task that already blocks the blocker (a direct cycle) are rejected.
Arguments:
- task: Blocked task ID (
tsk_...). - input: Request body.
- input.agent: Explicit owning agent (
agi_...) for privileged calls. - input.blocker: ID of the task that blocks this task (
tsk_...). - input.org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - input.team: Explicit owning team (
tem_...) for privileged calls. - input.user: Explicit owning user (
usr_...) for privileged calls.
Returns:
The updated (blocked) task.
def
delete(self, task: str, blocker: str) -> None:
1684 def delete(self, task: str, blocker: str) -> None: 1685 """ 1686 Remove a blocker from a task 1687 Removes the blocking relationship between the task in `blocker` and the 1688 specified task. Returns 204 No Content on success, or 404 if the given 1689 task is not currently marked as blocking this task. 1690 1691 Args: 1692 task: Blocked task ID (`tsk_...`). 1693 blocker: ID of the blocking task to remove (`tsk_...`). 1694 1695 Returns: 1696 Empty response body. HTTP 204 No Content on success. 1697 """ 1698 self._http.request(f"/api/v1/tasks/{task}/blockers/{blocker}", method="DELETE")
Remove a blocker from a task
Removes the blocking relationship between the task in blocker and the
specified task. Returns 204 No Content on success, or 404 if the given
task is not currently marked as blocking this task.
Arguments:
- task: Blocked task ID (
tsk_...). - blocker: ID of the blocking task to remove (
tsk_...).
Returns:
Empty response body. HTTP 204 No Content on success.
class
CommentResource:
1701class CommentResource: 1702 def __init__(self, http: SyncHttpClient): 1703 self._http = http 1704 1705 def list( 1706 self, 1707 task: str, 1708 *, 1709 team: str | None = None, 1710 user: str | None = None, 1711 agent: str | None = None, 1712 org: str | None = None, 1713 limit: int | None = None, 1714 after_cursor: str | None = None, 1715 ) -> CommentListResponse: 1716 """ 1717 List comments on a task 1718 Returns a bounded page of comments on the specified task, ordered by creation 1719 time ascending. App-scoped developer and server-to-server callers explicitly 1720 provide the owning `team`, `user`, or `agent` and `org`. 1721 1722 Args: 1723 task: Task ID (`tsk_...`). 1724 team: Explicit owning team (`tem_...`) for privileged calls. 1725 user: Explicit owning user (`usr_...`) for privileged calls. 1726 agent: Explicit owning agent (`agi_...`) for privileged calls. 1727 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1728 limit: Maximum comments to return. Capped at 100. 1729 after_cursor: Opaque cursor returned by the previous page. 1730 1731 Returns: 1732 Successful response 1733 """ 1734 query: dict[str, object] = {} 1735 if team is not None: 1736 query["team"] = team 1737 if user is not None: 1738 query["user"] = user 1739 if agent is not None: 1740 query["agent"] = agent 1741 if org is not None: 1742 query["org"] = org 1743 if limit is not None: 1744 query["limit"] = limit 1745 if after_cursor is not None: 1746 query["after_cursor"] = after_cursor 1747 return self._http.request( 1748 f"/api/v1/tasks/{task}/comments", 1749 query=query, 1750 response_type=CommentListResponse, 1751 ) 1752 1753 def create(self, task: str, input: CommentCreateInput) -> TaskComment: 1754 """ 1755 Create a comment on a task 1756 Posts a new comment on the specified task and returns the created comment. 1757 The task's owner is resolved from the task itself. 1758 1759 Args: 1760 task: Task ID (`tsk_...`). 1761 input: Request body. 1762 input.comment: Parameters for the comment to create, including its body. 1763 1764 Returns: 1765 The newly created comment. 1766 """ 1767 return self._http.request( 1768 f"/api/v1/tasks/{task}/comments", 1769 method="POST", 1770 body=input, 1771 response_type=TaskComment, 1772 ) 1773 1774 def delete(self, task: str, comment: str) -> None: 1775 """ 1776 Delete a task comment 1777 Permanently removes a comment from its task. This action cannot be undone. 1778 The task's owner is resolved from the task itself. 1779 Only the comment's author, an admin of the comment's organization, or an 1780 admin of the owning team may delete a comment. Returns `403 Forbidden` 1781 otherwise. 1782 1783 Args: 1784 task: Task ID (`tsk_...`). 1785 comment: Comment ID (`tcm_...`). 1786 1787 Returns: 1788 Empty body. The server responds with HTTP 204 No Content on success. 1789 """ 1790 self._http.request(f"/api/v1/tasks/{task}/comments/{comment}", method="DELETE") 1791 1792 def replace(self, task: str, comment: str, input: CommentReplaceInput) -> TaskComment: 1793 """ 1794 Update a task comment 1795 Replaces the body of an existing comment and returns the updated comment. 1796 The task's owner is resolved from the task itself. 1797 Only the comment's author, an admin of the comment's organization, or an 1798 admin of the owning team may edit a comment. Returns `403 Forbidden` 1799 otherwise. 1800 1801 Args: 1802 task: Task ID (`tsk_...`). 1803 comment: Comment ID (`tcm_...`). 1804 input: Request body. 1805 input.body: Replacement body for the comment. Must be non-empty. 1806 1807 Returns: 1808 The updated comment. 1809 """ 1810 return self._http.request( 1811 f"/api/v1/tasks/{task}/comments/{comment}", 1812 method="PUT", 1813 body=input, 1814 response_type=TaskComment, 1815 )
CommentResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> CommentListResponse:
1705 def list( 1706 self, 1707 task: str, 1708 *, 1709 team: str | None = None, 1710 user: str | None = None, 1711 agent: str | None = None, 1712 org: str | None = None, 1713 limit: int | None = None, 1714 after_cursor: str | None = None, 1715 ) -> CommentListResponse: 1716 """ 1717 List comments on a task 1718 Returns a bounded page of comments on the specified task, ordered by creation 1719 time ascending. App-scoped developer and server-to-server callers explicitly 1720 provide the owning `team`, `user`, or `agent` and `org`. 1721 1722 Args: 1723 task: Task ID (`tsk_...`). 1724 team: Explicit owning team (`tem_...`) for privileged calls. 1725 user: Explicit owning user (`usr_...`) for privileged calls. 1726 agent: Explicit owning agent (`agi_...`) for privileged calls. 1727 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1728 limit: Maximum comments to return. Capped at 100. 1729 after_cursor: Opaque cursor returned by the previous page. 1730 1731 Returns: 1732 Successful response 1733 """ 1734 query: dict[str, object] = {} 1735 if team is not None: 1736 query["team"] = team 1737 if user is not None: 1738 query["user"] = user 1739 if agent is not None: 1740 query["agent"] = agent 1741 if org is not None: 1742 query["org"] = org 1743 if limit is not None: 1744 query["limit"] = limit 1745 if after_cursor is not None: 1746 query["after_cursor"] = after_cursor 1747 return self._http.request( 1748 f"/api/v1/tasks/{task}/comments", 1749 query=query, 1750 response_type=CommentListResponse, 1751 )
List comments on a task
Returns a bounded page of comments on the specified task, ordered by creation
time ascending. App-scoped developer and server-to-server callers explicitly
provide the owning team, user, or agent and org.
Arguments:
- task: Task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum comments to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
def
create( self, task: str, input: CommentCreateInput) -> archastro.platform.types.tasks.TaskComment:
1753 def create(self, task: str, input: CommentCreateInput) -> TaskComment: 1754 """ 1755 Create a comment on a task 1756 Posts a new comment on the specified task and returns the created comment. 1757 The task's owner is resolved from the task itself. 1758 1759 Args: 1760 task: Task ID (`tsk_...`). 1761 input: Request body. 1762 input.comment: Parameters for the comment to create, including its body. 1763 1764 Returns: 1765 The newly created comment. 1766 """ 1767 return self._http.request( 1768 f"/api/v1/tasks/{task}/comments", 1769 method="POST", 1770 body=input, 1771 response_type=TaskComment, 1772 )
Create a comment on a task Posts a new comment on the specified task and returns the created comment. The task's owner is resolved from the task itself.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.comment: Parameters for the comment to create, including its body.
Returns:
The newly created comment.
def
delete(self, task: str, comment: str) -> None:
1774 def delete(self, task: str, comment: str) -> None: 1775 """ 1776 Delete a task comment 1777 Permanently removes a comment from its task. This action cannot be undone. 1778 The task's owner is resolved from the task itself. 1779 Only the comment's author, an admin of the comment's organization, or an 1780 admin of the owning team may delete a comment. Returns `403 Forbidden` 1781 otherwise. 1782 1783 Args: 1784 task: Task ID (`tsk_...`). 1785 comment: Comment ID (`tcm_...`). 1786 1787 Returns: 1788 Empty body. The server responds with HTTP 204 No Content on success. 1789 """ 1790 self._http.request(f"/api/v1/tasks/{task}/comments/{comment}", method="DELETE")
Delete a task comment
Permanently removes a comment from its task. This action cannot be undone.
The task's owner is resolved from the task itself.
Only the comment's author, an admin of the comment's organization, or an
admin of the owning team may delete a comment. Returns 403 Forbidden
otherwise.
Arguments:
- task: Task ID (
tsk_...). - comment: Comment ID (
tcm_...).
Returns:
Empty body. The server responds with HTTP 204 No Content on success.
def
replace( self, task: str, comment: str, input: CommentReplaceInput) -> archastro.platform.types.tasks.TaskComment:
1792 def replace(self, task: str, comment: str, input: CommentReplaceInput) -> TaskComment: 1793 """ 1794 Update a task comment 1795 Replaces the body of an existing comment and returns the updated comment. 1796 The task's owner is resolved from the task itself. 1797 Only the comment's author, an admin of the comment's organization, or an 1798 admin of the owning team may edit a comment. Returns `403 Forbidden` 1799 otherwise. 1800 1801 Args: 1802 task: Task ID (`tsk_...`). 1803 comment: Comment ID (`tcm_...`). 1804 input: Request body. 1805 input.body: Replacement body for the comment. Must be non-empty. 1806 1807 Returns: 1808 The updated comment. 1809 """ 1810 return self._http.request( 1811 f"/api/v1/tasks/{task}/comments/{comment}", 1812 method="PUT", 1813 body=input, 1814 response_type=TaskComment, 1815 )
Update a task comment
Replaces the body of an existing comment and returns the updated comment.
The task's owner is resolved from the task itself.
Only the comment's author, an admin of the comment's organization, or an
admin of the owning team may edit a comment. Returns 403 Forbidden
otherwise.
Arguments:
- task: Task ID (
tsk_...). - comment: Comment ID (
tcm_...). - input: Request body.
- input.body: Replacement body for the comment. Must be non-empty.
Returns:
The updated comment.
class
LeaseResource:
1818class LeaseResource: 1819 def __init__(self, http: SyncHttpClient): 1820 self._http = http 1821 1822 def remove(self, task: str) -> None: 1823 """ 1824 Release a task session lease 1825 Releases the authenticated assignee's matching live task lease. Repeating a 1826 release after the lease is absent succeeds. A different live successor lease 1827 returns a mismatch. 1828 1829 Args: 1830 task: Task ID (`tsk_...`). 1831 1832 Returns: 1833 Empty response. HTTP 204 is returned after release is accepted. 1834 """ 1835 self._http.request(f"/api/v1/tasks/{task}/lease", method="DELETE") 1836 1837 def list(self, task: str) -> TaskSessionLeaseSummary | None: 1838 """ 1839 Retrieve a task's current session lease 1840 Returns the authenticated assignee's viewer-safe live lease summary, or null 1841 when no live lease exists. Fencing and opaque session identifiers are never 1842 included. 1843 1844 Args: 1845 task: Task ID (`tsk_...`). 1846 1847 Returns: 1848 Viewer-safe live lease summary, or null. 1849 """ 1850 return self._http.request( 1851 f"/api/v1/tasks/{task}/lease", 1852 response_type=TaskSessionLeaseSummary | None, 1853 ) 1854 1855 def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: 1856 """ 1857 Claim a task for a coding session 1858 Atomically claims a user-assigned task for the authenticated user's coding 1859 session. The caller generates and retains both UUIDs. An exact retry returns 1860 the existing lease without extending it; another live holder produces a 1861 conflict. Developer and server-to-server credentials cannot impersonate the 1862 assigned user. 1863 1864 Args: 1865 task: Task ID (`tsk_...`). 1866 input: Request body. 1867 input.harness: Bounded harness identifier. 1868 input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. 1869 input.lease_id: Caller-generated lease UUID. 1870 input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. 1871 input.session_id: Caller-generated coding-session UUID. 1872 input.session_name: Human-readable coding-session label. 1873 1874 Returns: 1875 The caller-held lease, including its fencing token. 1876 """ 1877 return self._http.request( 1878 f"/api/v1/tasks/{task}/lease", 1879 method="POST", 1880 body=input, 1881 response_type=TaskSessionLease, 1882 ) 1883 1884 def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: 1885 """ 1886 Renew a task session lease 1887 Renews the authenticated assignee's matching live task lease. Both 1888 caller-generated UUIDs must match the aggregate's current lease. 1889 1890 Args: 1891 task: Task ID (`tsk_...`). 1892 input: Request body. 1893 input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds. 1894 input.lease_id: Current caller-held lease UUID. 1895 input.session_id: Current coding-session UUID. 1896 1897 Returns: 1898 The renewed caller-held lease. 1899 """ 1900 return self._http.request( 1901 f"/api/v1/tasks/{task}/lease/renew", 1902 method="POST", 1903 body=input, 1904 response_type=TaskSessionLease, 1905 )
LeaseResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
remove(self, task: str) -> None:
1822 def remove(self, task: str) -> None: 1823 """ 1824 Release a task session lease 1825 Releases the authenticated assignee's matching live task lease. Repeating a 1826 release after the lease is absent succeeds. A different live successor lease 1827 returns a mismatch. 1828 1829 Args: 1830 task: Task ID (`tsk_...`). 1831 1832 Returns: 1833 Empty response. HTTP 204 is returned after release is accepted. 1834 """ 1835 self._http.request(f"/api/v1/tasks/{task}/lease", method="DELETE")
Release a task session lease Releases the authenticated assignee's matching live task lease. Repeating a release after the lease is absent succeeds. A different live successor lease returns a mismatch.
Arguments:
- task: Task ID (
tsk_...).
Returns:
Empty response. HTTP 204 is returned after release is accepted.
1837 def list(self, task: str) -> TaskSessionLeaseSummary | None: 1838 """ 1839 Retrieve a task's current session lease 1840 Returns the authenticated assignee's viewer-safe live lease summary, or null 1841 when no live lease exists. Fencing and opaque session identifiers are never 1842 included. 1843 1844 Args: 1845 task: Task ID (`tsk_...`). 1846 1847 Returns: 1848 Viewer-safe live lease summary, or null. 1849 """ 1850 return self._http.request( 1851 f"/api/v1/tasks/{task}/lease", 1852 response_type=TaskSessionLeaseSummary | None, 1853 )
Retrieve a task's current session lease Returns the authenticated assignee's viewer-safe live lease summary, or null when no live lease exists. Fencing and opaque session identifiers are never included.
Arguments:
- task: Task ID (
tsk_...).
Returns:
Viewer-safe live lease summary, or null.
def
create( self, task: str, input: LeaseCreateInput) -> archastro.platform.types.tasks.TaskSessionLease:
1855 def create(self, task: str, input: LeaseCreateInput) -> TaskSessionLease: 1856 """ 1857 Claim a task for a coding session 1858 Atomically claims a user-assigned task for the authenticated user's coding 1859 session. The caller generates and retains both UUIDs. An exact retry returns 1860 the existing lease without extending it; another live holder produces a 1861 conflict. Developer and server-to-server credentials cannot impersonate the 1862 assigned user. 1863 1864 Args: 1865 task: Task ID (`tsk_...`). 1866 input: Request body. 1867 input.harness: Bounded harness identifier. 1868 input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds. 1869 input.lease_id: Caller-generated lease UUID. 1870 input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers. 1871 input.session_id: Caller-generated coding-session UUID. 1872 input.session_name: Human-readable coding-session label. 1873 1874 Returns: 1875 The caller-held lease, including its fencing token. 1876 """ 1877 return self._http.request( 1878 f"/api/v1/tasks/{task}/lease", 1879 method="POST", 1880 body=input, 1881 response_type=TaskSessionLease, 1882 )
Claim a task for a coding session Atomically claims a user-assigned task for the authenticated user's coding session. The caller generates and retains both UUIDs. An exact retry returns the existing lease without extending it; another live holder produces a conflict. Developer and server-to-server credentials cannot impersonate the assigned user.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.harness: Bounded harness identifier.
- input.lease_duration_seconds: Requested lease lifetime in seconds; the task aggregate enforces its bounds.
- input.lease_id: Caller-generated lease UUID.
- input.require_ready: Conservatively reject the claim when the current task projection has unfinished blockers.
- input.session_id: Caller-generated coding-session UUID.
- input.session_name: Human-readable coding-session label.
Returns:
The caller-held lease, including its fencing token.
def
renew( self, task: str, input: LeaseRenewInput) -> archastro.platform.types.tasks.TaskSessionLease:
1884 def renew(self, task: str, input: LeaseRenewInput) -> TaskSessionLease: 1885 """ 1886 Renew a task session lease 1887 Renews the authenticated assignee's matching live task lease. Both 1888 caller-generated UUIDs must match the aggregate's current lease. 1889 1890 Args: 1891 task: Task ID (`tsk_...`). 1892 input: Request body. 1893 input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds. 1894 input.lease_id: Current caller-held lease UUID. 1895 input.session_id: Current coding-session UUID. 1896 1897 Returns: 1898 The renewed caller-held lease. 1899 """ 1900 return self._http.request( 1901 f"/api/v1/tasks/{task}/lease/renew", 1902 method="POST", 1903 body=input, 1904 response_type=TaskSessionLease, 1905 )
Renew a task session lease Renews the authenticated assignee's matching live task lease. Both caller-generated UUIDs must match the aggregate's current lease.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.lease_duration_seconds: Requested renewed lifetime in seconds; the task aggregate enforces its bounds.
- input.lease_id: Current caller-held lease UUID.
- input.session_id: Current coding-session UUID.
Returns:
The renewed caller-held lease.
class
LinkResource:
1908class LinkResource: 1909 def __init__(self, http: SyncHttpClient): 1910 self._http = http 1911 1912 def remove(self, task: str) -> None: 1913 """ 1914 Remove an external link from a task 1915 1916 Args: 1917 task: Task ID (`tsk_...`). 1918 1919 Returns: 1920 HTTP 204 on success. 1921 """ 1922 self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE") 1923 1924 def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: 1925 """ 1926 Add an external link to a task 1927 1928 Args: 1929 task: Task ID (`tsk_...`). 1930 input: Request body. 1931 input.external_scope: External container ID. 1932 input.object_id: External object ID. 1933 input.object_type: External object type. 1934 1935 Returns: 1936 The created external link. 1937 """ 1938 return self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input)
LinkResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
remove(self, task: str) -> None:
1912 def remove(self, task: str) -> None: 1913 """ 1914 Remove an external link from a task 1915 1916 Args: 1917 task: Task ID (`tsk_...`). 1918 1919 Returns: 1920 HTTP 204 on success. 1921 """ 1922 self._http.request(f"/api/v1/tasks/{task}/links", method="DELETE")
Remove an external link from a task
Arguments:
- task: Task ID (
tsk_...).
Returns:
HTTP 204 on success.
1924 def create(self, task: str, input: LinkCreateInput) -> dict[str, Any]: 1925 """ 1926 Add an external link to a task 1927 1928 Args: 1929 task: Task ID (`tsk_...`). 1930 input: Request body. 1931 input.external_scope: External container ID. 1932 input.object_id: External object ID. 1933 input.object_type: External object type. 1934 1935 Returns: 1936 The created external link. 1937 """ 1938 return self._http.request(f"/api/v1/tasks/{task}/links", method="POST", body=input)
Add an external link to a task
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.external_scope: External container ID.
- input.object_id: External object ID.
- input.object_type: External object type.
Returns:
The created external link.
class
TaskResource:
1941class TaskResource: 1942 def __init__(self, http: SyncHttpClient): 1943 self._http = http 1944 self.blockers = BlockerResource(http) 1945 self.comments = CommentResource(http) 1946 self.lease = LeaseResource(http) 1947 self.links = LinkResource(http) 1948 1949 def delete(self, task: str) -> None: 1950 """ 1951 Delete a task 1952 Deletes a task from task lists and detail views. The task event stream is 1953 retained for auditability, while comments are removed and direct subtasks 1954 are promoted to top-level tasks. 1955 The delete event is accepted before the read model is updated. Clients 1956 should remove the task from local collections immediately; subsequent reads 1957 converge once the projection processes the event. 1958 Authenticated users may delete tasks they can access using their session 1959 identity. App-scoped developer and server-to-server callers must explicitly 1960 supply the task's `org` and owner. `team` or `user` identifies that owner; 1961 when neither is present, `agent` identifies an agent-owned task. With a team 1962 or user owner, `agent` identifies the acting principal. Each reference is 1963 validated before deletion. 1964 1965 Args: 1966 task: Task ID (`tsk_...`). 1967 1968 Returns: 1969 Empty response. HTTP 204 is returned after the delete event is accepted. 1970 """ 1971 self._http.request(f"/api/v1/tasks/{task}", method="DELETE") 1972 1973 def get( 1974 self, 1975 task: str, 1976 *, 1977 team: str | None = None, 1978 user: str | None = None, 1979 agent: str | None = None, 1980 org: str | None = None, 1981 ) -> Task: 1982 """ 1983 Retrieve a task 1984 Returns the full task object for the specified task ID. Authenticated users 1985 and agents resolve access through their session. App-scoped developer and 1986 server-to-server callers explicitly provide the owning `team`, `user`, or `agent` and 1987 `org`. Callers without access receive a 404. 1988 1989 Args: 1990 task: Task ID (`tsk_...`). 1991 team: Explicit owning team (`tem_...`) for privileged calls. 1992 user: Explicit owning user (`usr_...`) for privileged calls. 1993 agent: Explicit owning agent (`agi_...`) for privileged calls. 1994 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1995 1996 Returns: 1997 The requested task. 1998 """ 1999 query: dict[str, object] = {} 2000 if team is not None: 2001 query["team"] = team 2002 if user is not None: 2003 query["user"] = user 2004 if agent is not None: 2005 query["agent"] = agent 2006 if org is not None: 2007 query["org"] = org 2008 return self._http.request(f"/api/v1/tasks/{task}", query=query, response_type=Task) 2009 2010 def replace(self, task: str, input: TaskReplaceInput) -> Task: 2011 """ 2012 Update a task 2013 Updates the supplied fields on a task and returns the complete updated task. 2014 Authenticated users use their session identity. App-scoped developer and 2015 server-to-server callers must explicitly supply the task's `org` and owner. 2016 `team` or `user` identifies that owner; when neither is present, `agent` 2017 identifies an agent-owned task. With a team or user owner, `agent` identifies 2018 the acting principal. Every reference is validated before the update. 2019 A cooperating coding-session client may supply both `lease_id` and 2020 `lease_session_id`. The task aggregate fences that update against the live 2021 lease and records server-sourced session provenance. Omitting both remains a 2022 normal authorized human/API update. 2023 2024 Args: 2025 task: Task ID (`tsk_...`). 2026 input: Request body. 2027 input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. 2028 input.description: Updated long-form description. 2029 input.due_date: Updated due date in ISO 8601 format, or null to clear it. 2030 input.epic: Replacement grouping label. Pass null to clear it. 2031 input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. 2032 input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. 2033 input.links: Replacement related-links object. 2034 input.metadata: Replacement task metadata object. 2035 input.name: Updated display name for the task. 2036 input.org: Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization. 2037 input.owner_agent: Assign to an agent by public ID (`agi_...`). 2038 input.owner_user: Assign to a user by public ID (`usr_...`). 2039 input.parent: 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. 2040 input.priority: Updated priority from 0 (highest) to 4 (lowest). 2041 input.source_id: Replacement source object identity. Must be supplied with the other source fields. 2042 input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. 2043 input.source_type: Replacement source object kind. Must be supplied with the other source fields. 2044 input.status: Updated status: `open`, `in_progress`, or `done`. 2045 input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. 2046 input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. 2047 input.user: Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member. 2048 2049 Returns: 2050 The updated task. 2051 """ 2052 return self._http.request( 2053 f"/api/v1/tasks/{task}", 2054 method="PUT", 2055 body=input, 2056 response_type=Task, 2057 ) 2058 2059 def activity( 2060 self, 2061 task: str, 2062 *, 2063 team: str | None = None, 2064 user: str | None = None, 2065 agent: str | None = None, 2066 org: str | None = None, 2067 limit: int | None = None, 2068 after_cursor: str | None = None, 2069 ) -> TaskActivityResponse: 2070 """ 2071 List a task's activity 2072 Returns a bounded chronological page of activity for the specified task. 2073 App-scoped developer and server-to-server callers explicitly provide the 2074 owning `team`, `user`, or `agent` and `org`. 2075 2076 Args: 2077 task: Task ID (`tsk_...`). 2078 team: Explicit owning team (`tem_...`) for privileged calls. 2079 user: Explicit owning user (`usr_...`) for privileged calls. 2080 agent: Explicit owning agent (`agi_...`) for privileged calls. 2081 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2082 limit: Maximum entries to return. Capped at 100. 2083 after_cursor: Opaque cursor returned by the previous page. 2084 2085 Returns: 2086 Successful response 2087 """ 2088 query: dict[str, object] = {} 2089 if team is not None: 2090 query["team"] = team 2091 if user is not None: 2092 query["user"] = user 2093 if agent is not None: 2094 query["agent"] = agent 2095 if org is not None: 2096 query["org"] = org 2097 if limit is not None: 2098 query["limit"] = limit 2099 if after_cursor is not None: 2100 query["after_cursor"] = after_cursor 2101 return self._http.request( 2102 f"/api/v1/tasks/{task}/activity", 2103 query=query, 2104 response_type=TaskActivityResponse, 2105 ) 2106 2107 def blocking( 2108 self, 2109 task: str, 2110 *, 2111 team: str | None = None, 2112 user: str | None = None, 2113 agent: str | None = None, 2114 org: str | None = None, 2115 limit: int | None = None, 2116 after_cursor: str | None = None, 2117 ) -> TaskBlockingResponse: 2118 """ 2119 List the tasks a task blocks 2120 Returns a bounded page of the tasks that the specified task is marked as 2121 blocking (the inverse of `GET /tasks/{task}/blockers`), newest first. 2122 The task's owner is resolved from the task itself. 2123 2124 Args: 2125 task: Blocking task ID (`tsk_...`). 2126 team: Explicit owning team (`tem_...`) for privileged calls. 2127 user: Explicit owning user (`usr_...`) for privileged calls. 2128 agent: Explicit owning agent (`agi_...`) for privileged calls. 2129 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2130 limit: Maximum tasks to return. Capped at 100. 2131 after_cursor: Opaque cursor returned by the previous page. 2132 2133 Returns: 2134 Successful response 2135 """ 2136 query: dict[str, object] = {} 2137 if team is not None: 2138 query["team"] = team 2139 if user is not None: 2140 query["user"] = user 2141 if agent is not None: 2142 query["agent"] = agent 2143 if org is not None: 2144 query["org"] = org 2145 if limit is not None: 2146 query["limit"] = limit 2147 if after_cursor is not None: 2148 query["after_cursor"] = after_cursor 2149 return self._http.request( 2150 f"/api/v1/tasks/{task}/blocking", 2151 query=query, 2152 response_type=TaskBlockingResponse, 2153 ) 2154 2155 def subtasks( 2156 self, 2157 task: str, 2158 *, 2159 team: str | None = None, 2160 user: str | None = None, 2161 agent: str | None = None, 2162 org: str | None = None, 2163 limit: int | None = None, 2164 after_cursor: str | None = None, 2165 ) -> TaskSubtasksResponse: 2166 """ 2167 List a task's subtasks 2168 Returns a bounded page of the specified task's subtasks (tasks whose 2169 `parent` is this task), newest first. Subtasks nest exactly one level, so 2170 entries never have subtasks of their own. Privileged callers explicitly 2171 provide the owning `team`, `user`, or `agent` and `org`. 2172 2173 Args: 2174 task: Parent task ID (`tsk_...`). 2175 team: Explicit owning team (`tem_...`) for privileged calls. 2176 user: Explicit owning user (`usr_...`) for privileged calls. 2177 agent: Explicit owning agent (`agi_...`) for privileged calls. 2178 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2179 limit: Maximum subtasks to return. Capped at 100. 2180 after_cursor: Opaque cursor returned by the previous page. 2181 2182 Returns: 2183 Successful response 2184 """ 2185 query: dict[str, object] = {} 2186 if team is not None: 2187 query["team"] = team 2188 if user is not None: 2189 query["user"] = user 2190 if agent is not None: 2191 query["agent"] = agent 2192 if org is not None: 2193 query["org"] = org 2194 if limit is not None: 2195 query["limit"] = limit 2196 if after_cursor is not None: 2197 query["after_cursor"] = after_cursor 2198 return self._http.request( 2199 f"/api/v1/tasks/{task}/subtasks", 2200 query=query, 2201 response_type=TaskSubtasksResponse, 2202 )
TaskResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
delete(self, task: str) -> None:
1949 def delete(self, task: str) -> None: 1950 """ 1951 Delete a task 1952 Deletes a task from task lists and detail views. The task event stream is 1953 retained for auditability, while comments are removed and direct subtasks 1954 are promoted to top-level tasks. 1955 The delete event is accepted before the read model is updated. Clients 1956 should remove the task from local collections immediately; subsequent reads 1957 converge once the projection processes the event. 1958 Authenticated users may delete tasks they can access using their session 1959 identity. App-scoped developer and server-to-server callers must explicitly 1960 supply the task's `org` and owner. `team` or `user` identifies that owner; 1961 when neither is present, `agent` identifies an agent-owned task. With a team 1962 or user owner, `agent` identifies the acting principal. Each reference is 1963 validated before deletion. 1964 1965 Args: 1966 task: Task ID (`tsk_...`). 1967 1968 Returns: 1969 Empty response. HTTP 204 is returned after the delete event is accepted. 1970 """ 1971 self._http.request(f"/api/v1/tasks/{task}", method="DELETE")
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.
Arguments:
- task: Task ID (
tsk_...).
Returns:
Empty response. HTTP 204 is returned after the delete event is accepted.
def
get( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None) -> archastro.platform.types.tasks.Task:
1973 def get( 1974 self, 1975 task: str, 1976 *, 1977 team: str | None = None, 1978 user: str | None = None, 1979 agent: str | None = None, 1980 org: str | None = None, 1981 ) -> Task: 1982 """ 1983 Retrieve a task 1984 Returns the full task object for the specified task ID. Authenticated users 1985 and agents resolve access through their session. App-scoped developer and 1986 server-to-server callers explicitly provide the owning `team`, `user`, or `agent` and 1987 `org`. Callers without access receive a 404. 1988 1989 Args: 1990 task: Task ID (`tsk_...`). 1991 team: Explicit owning team (`tem_...`) for privileged calls. 1992 user: Explicit owning user (`usr_...`) for privileged calls. 1993 agent: Explicit owning agent (`agi_...`) for privileged calls. 1994 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 1995 1996 Returns: 1997 The requested task. 1998 """ 1999 query: dict[str, object] = {} 2000 if team is not None: 2001 query["team"] = team 2002 if user is not None: 2003 query["user"] = user 2004 if agent is not None: 2005 query["agent"] = agent 2006 if org is not None: 2007 query["org"] = org 2008 return self._http.request(f"/api/v1/tasks/{task}", query=query, response_type=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.
Arguments:
- task: Task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped.
Returns:
The requested task.
2010 def replace(self, task: str, input: TaskReplaceInput) -> Task: 2011 """ 2012 Update a task 2013 Updates the supplied fields on a task and returns the complete updated task. 2014 Authenticated users use their session identity. App-scoped developer and 2015 server-to-server callers must explicitly supply the task's `org` and owner. 2016 `team` or `user` identifies that owner; when neither is present, `agent` 2017 identifies an agent-owned task. With a team or user owner, `agent` identifies 2018 the acting principal. Every reference is validated before the update. 2019 A cooperating coding-session client may supply both `lease_id` and 2020 `lease_session_id`. The task aggregate fences that update against the live 2021 lease and records server-sourced session provenance. Omitting both remains a 2022 normal authorized human/API update. 2023 2024 Args: 2025 task: Task ID (`tsk_...`). 2026 input: Request body. 2027 input.agent: Explicit agent (`agi_...`). It is the owner when `team` and `user` are absent; otherwise it is the acting principal. 2028 input.description: Updated long-form description. 2029 input.due_date: Updated due date in ISO 8601 format, or null to clear it. 2030 input.epic: Replacement grouping label. Pass null to clear it. 2031 input.lease_id: Current caller-held lease UUID. Must be paired with `lease_session_id`. 2032 input.lease_session_id: Current coding-session UUID. Must be paired with `lease_id`. 2033 input.links: Replacement related-links object. 2034 input.metadata: Replacement task metadata object. 2035 input.name: Updated display name for the task. 2036 input.org: Explicit organization (`org_...`) for a developer or server-to-server call. Pass null for an owner outside an organization. 2037 input.owner_agent: Assign to an agent by public ID (`agi_...`). 2038 input.owner_user: Assign to a user by public ID (`usr_...`). 2039 input.parent: 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. 2040 input.priority: Updated priority from 0 (highest) to 4 (lowest). 2041 input.source_id: Replacement source object identity. Must be supplied with the other source fields. 2042 input.source_scope: Replacement source container. Pass together with `source_type` and `source_id`, or pass all three as null to clear the source. 2043 input.source_type: Replacement source object kind. Must be supplied with the other source fields. 2044 input.status: Updated status: `open`, `in_progress`, or `done`. 2045 input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags. 2046 input.team: Explicit owning team (`tem_...`) for a developer or server-to-server call. 2047 input.user: Explicit user (`usr_...`) for a developer or server-to-server call. With `team`, this identifies the acting team member. 2048 2049 Returns: 2050 The updated task. 2051 """ 2052 return self._http.request( 2053 f"/api/v1/tasks/{task}", 2054 method="PUT", 2055 body=input, 2056 response_type=Task, 2057 )
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.
Arguments:
- task: Task ID (
tsk_...). - input: Request body.
- input.agent: Explicit agent (
agi_...). It is the owner whenteamanduserare absent; otherwise it is the acting principal. - input.description: Updated long-form description.
- input.due_date: Updated due date in ISO 8601 format, or null to clear it.
- input.epic: Replacement grouping label. Pass null to clear it.
- input.lease_id: Current caller-held lease UUID. Must be paired with
lease_session_id. - input.lease_session_id: Current coding-session UUID. Must be paired with
lease_id. - input.links: Replacement related-links object.
- input.metadata: Replacement task metadata object.
- input.name: Updated display name for the task.
- input.org: Explicit organization (
org_...) for a developer or server-to-server call. Pass null for an owner outside an organization. - input.owner_agent: Assign to an agent by public ID (
agi_...). - input.owner_user: Assign to a user by public ID (
usr_...). - input.parent: 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. - input.priority: Updated priority from 0 (highest) to 4 (lowest).
- input.source_id: Replacement source object identity. Must be supplied with the other source fields.
- input.source_scope: Replacement source container. Pass together with
source_typeandsource_id, or pass all three as null to clear the source. - input.source_type: Replacement source object kind. Must be supplied with the other source fields.
- input.status: Updated status:
open,in_progress, ordone. - input.tags: Replacement tag list (max 20, each up to 40 characters; normalized to lowercase). Pass an empty array to clear all tags.
- input.team: Explicit owning team (
tem_...) for a developer or server-to-server call. - input.user: Explicit user (
usr_...) for a developer or server-to-server call. Withteam, this identifies the acting team member.
Returns:
The updated task.
def
activity( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> TaskActivityResponse:
2059 def activity( 2060 self, 2061 task: str, 2062 *, 2063 team: str | None = None, 2064 user: str | None = None, 2065 agent: str | None = None, 2066 org: str | None = None, 2067 limit: int | None = None, 2068 after_cursor: str | None = None, 2069 ) -> TaskActivityResponse: 2070 """ 2071 List a task's activity 2072 Returns a bounded chronological page of activity for the specified task. 2073 App-scoped developer and server-to-server callers explicitly provide the 2074 owning `team`, `user`, or `agent` and `org`. 2075 2076 Args: 2077 task: Task ID (`tsk_...`). 2078 team: Explicit owning team (`tem_...`) for privileged calls. 2079 user: Explicit owning user (`usr_...`) for privileged calls. 2080 agent: Explicit owning agent (`agi_...`) for privileged calls. 2081 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2082 limit: Maximum entries to return. Capped at 100. 2083 after_cursor: Opaque cursor returned by the previous page. 2084 2085 Returns: 2086 Successful response 2087 """ 2088 query: dict[str, object] = {} 2089 if team is not None: 2090 query["team"] = team 2091 if user is not None: 2092 query["user"] = user 2093 if agent is not None: 2094 query["agent"] = agent 2095 if org is not None: 2096 query["org"] = org 2097 if limit is not None: 2098 query["limit"] = limit 2099 if after_cursor is not None: 2100 query["after_cursor"] = after_cursor 2101 return self._http.request( 2102 f"/api/v1/tasks/{task}/activity", 2103 query=query, 2104 response_type=TaskActivityResponse, 2105 )
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.
Arguments:
- task: Task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum entries to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
def
blocking( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> TaskBlockingResponse:
2107 def blocking( 2108 self, 2109 task: str, 2110 *, 2111 team: str | None = None, 2112 user: str | None = None, 2113 agent: str | None = None, 2114 org: str | None = None, 2115 limit: int | None = None, 2116 after_cursor: str | None = None, 2117 ) -> TaskBlockingResponse: 2118 """ 2119 List the tasks a task blocks 2120 Returns a bounded page of the tasks that the specified task is marked as 2121 blocking (the inverse of `GET /tasks/{task}/blockers`), newest first. 2122 The task's owner is resolved from the task itself. 2123 2124 Args: 2125 task: Blocking task ID (`tsk_...`). 2126 team: Explicit owning team (`tem_...`) for privileged calls. 2127 user: Explicit owning user (`usr_...`) for privileged calls. 2128 agent: Explicit owning agent (`agi_...`) for privileged calls. 2129 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2130 limit: Maximum tasks to return. Capped at 100. 2131 after_cursor: Opaque cursor returned by the previous page. 2132 2133 Returns: 2134 Successful response 2135 """ 2136 query: dict[str, object] = {} 2137 if team is not None: 2138 query["team"] = team 2139 if user is not None: 2140 query["user"] = user 2141 if agent is not None: 2142 query["agent"] = agent 2143 if org is not None: 2144 query["org"] = org 2145 if limit is not None: 2146 query["limit"] = limit 2147 if after_cursor is not None: 2148 query["after_cursor"] = after_cursor 2149 return self._http.request( 2150 f"/api/v1/tasks/{task}/blocking", 2151 query=query, 2152 response_type=TaskBlockingResponse, 2153 )
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.
Arguments:
- task: Blocking task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
def
subtasks( self, task: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> TaskSubtasksResponse:
2155 def subtasks( 2156 self, 2157 task: str, 2158 *, 2159 team: str | None = None, 2160 user: str | None = None, 2161 agent: str | None = None, 2162 org: str | None = None, 2163 limit: int | None = None, 2164 after_cursor: str | None = None, 2165 ) -> TaskSubtasksResponse: 2166 """ 2167 List a task's subtasks 2168 Returns a bounded page of the specified task's subtasks (tasks whose 2169 `parent` is this task), newest first. Subtasks nest exactly one level, so 2170 entries never have subtasks of their own. Privileged callers explicitly 2171 provide the owning `team`, `user`, or `agent` and `org`. 2172 2173 Args: 2174 task: Parent task ID (`tsk_...`). 2175 team: Explicit owning team (`tem_...`) for privileged calls. 2176 user: Explicit owning user (`usr_...`) for privileged calls. 2177 agent: Explicit owning agent (`agi_...`) for privileged calls. 2178 org: Explicit organization (`org_...`) for privileged calls; pass null when unscoped. 2179 limit: Maximum subtasks to return. Capped at 100. 2180 after_cursor: Opaque cursor returned by the previous page. 2181 2182 Returns: 2183 Successful response 2184 """ 2185 query: dict[str, object] = {} 2186 if team is not None: 2187 query["team"] = team 2188 if user is not None: 2189 query["user"] = user 2190 if agent is not None: 2191 query["agent"] = agent 2192 if org is not None: 2193 query["org"] = org 2194 if limit is not None: 2195 query["limit"] = limit 2196 if after_cursor is not None: 2197 query["after_cursor"] = after_cursor 2198 return self._http.request( 2199 f"/api/v1/tasks/{task}/subtasks", 2200 query=query, 2201 response_type=TaskSubtasksResponse, 2202 )
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.
Arguments:
- task: Parent task ID (
tsk_...). - team: Explicit owning team (
tem_...) for privileged calls. - user: Explicit owning user (
usr_...) for privileged calls. - agent: Explicit owning agent (
agi_...) for privileged calls. - org: Explicit organization (
org_...) for privileged calls; pass null when unscoped. - limit: Maximum subtasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response