archastro.platform.v1.resources.orgs
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: e193124aa024 4 5from __future__ import annotations 6 7import builtins 8from datetime import datetime 9from typing import Any, Literal, Required, TypedDict 10 11from pydantic import BaseModel, Field 12 13from ...runtime.http_client import HttpClient, SyncHttpClient 14from ...types.tasks import Task, TaskEnsureResult 15from ...types.threads import Thread 16 17 18class OrgTaskCreateInputTask(TypedDict, total=False): 19 description: str | None 20 "Optional long-form description or notes for the task. Supports plain text." 21 due_date: datetime | None 22 "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." 23 epic: str | None 24 "Optional free-form grouping label." 25 id: str | None 26 "Optional caller-generated task public ID (`tsk_...`). Persist it before creating a task when creation must survive a lost response. An existing ID returns 409 without modifying the task; read the task by ID to reconcile. Omit for a server-generated ID." 27 links: dict[str, Any] | None 28 "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links)." 29 metadata: dict[str, Any] | None 30 "Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata." 31 name: Required[str] 32 "Human-readable title for the task." 33 owner_agent: str | None 34 "ID of the agent to assign as owner (`agi_...`). Mutually exclusive with `owner_user`; omit to leave the task unassigned." 35 owner_user: str | None 36 "ID of the user to assign as owner (`usr_...`). Mutually exclusive with `owner_agent`; omit to leave the task unassigned." 37 parent: str | None 38 "Create this task as a subtask of an existing top-level task (`tsk_...`). Subtasks nest exactly one level." 39 priority: int | None 40 "Priority level from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when omitted." 41 project_id: str | None 42 "Optional project ID (`prj_...`). Pass null to clear it." 43 source_id: str | None 44 "Source object identity (for example `ArchAstro/firstlanding`)." 45 source_scope: str | None 46 "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`." 47 source_type: str | None 48 "Kind of source object (for example `repository`)." 49 status: str | None 50 'Initial status for the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`. Defaults to `"open"` when omitted.' 51 tags: list[str] | None 52 "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated." 53 target_binary: str | None 54 "Binary that must run this work, as a lowercase identifier of 1-64 characters (letters, digits, `.`, `_`, `-`; for example `my-cli`). Must be supplied with `target_version`." 55 target_version: str | None 56 "Minimum semantic version of `target_binary` that can run this work (`MAJOR.MINOR.PATCH` with optional prerelease and build, no leading `v`). Must be supplied with `target_binary`." 57 thread: str | None 58 "Bind the task to a thread (`thr_...`) owned by the same team or user as the task. A bound task appears in that thread's task scope, exactly like a task filed from inside the conversation. Omit for a task not tied to a conversation." 59 60 61class OrgTaskCreateInput(TypedDict, total=False): 62 "Create a task for an organization" 63 64 agent: str | None 65 "Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization." 66 task: Required[OrgTaskCreateInputTask] 67 "Attributes for the task to create. `name` is required; all other fields are optional." 68 user: str | None 69 "Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`." 70 71 72class OrgTaskBySourceInput(TypedDict, total=False): 73 "Find or create a task by source" 74 75 agent: str | None 76 "Explicit acting agent for privileged callers." 77 description: str | None 78 "Initial task description." 79 epic: str | None 80 "Initial epic grouping." 81 name: Required[str] 82 "Initial task name." 83 source_id: Required[str] 84 "Source identity, for example owner/repo#123." 85 source_scope: Required[str] 86 "Source scope, for example github." 87 source_type: Required[str] 88 "Source type, for example pull_request." 89 status: str | None 90 "Initial task status." 91 team: str | None 92 "Team owner." 93 user: str | None 94 "User owner, or explicit acting user on a team route." 95 96 97class OrgThreadCreateInputThreadMembersItem(TypedDict): 98 id: str 99 "Public user (`usr_...`) or agent (`agt_...`) ID matching `type`." 100 type: Literal["user", "agent"] 101 "Member kind. Use `user` for a user ID or `agent` for an agent ID." 102 103 104class OrgThreadCreateInputThreadProfilePicture(TypedDict, total=False): 105 data: str | None 106 "Base64-encoded image bytes." 107 filename: str | None 108 "Original filename of the uploaded image, used for display and content-type inference." 109 mime_type: str | None 110 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.' 111 112 113class OrgThreadCreateInputThreadSettings(TypedDict, total=False): 114 agent_enabled: bool | None 115 "Whether the AI agent is active for this thread. `true` enables AI responses; `false` disables them. Defaults to `true` when settings have not been explicitly configured. `null` when a client explicitly cleared the setting." 116 117 118class OrgThreadCreateInputThread(TypedDict, total=False): 119 create_legacy_agent: bool | None 120 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 121 description: str | None 122 "Optional longer description of the thread's purpose. `null` if not provided." 123 is_unlisted: bool | None 124 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 125 key: str | None 126 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 127 kind: Literal["personal", "feed"] | None 128 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. `feed` is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers." 129 members: list[OrgThreadCreateInputThreadMembersItem] | None 130 "Users and agents to add atomically when the thread is created. Each target must pass the same authorization rules as a post-creation member add. Slack mirror threads reject non-empty caller-supplied rosters because their membership is sync-owned." 131 metadata: dict[str, Any] | None 132 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 133 muted: bool | None 134 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 135 org_id: str | None 136 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 137 profile_picture: OrgThreadCreateInputThreadProfilePicture | None 138 "Optional profile image for the thread, provided as a base64-encoded payload." 139 settings: OrgThreadCreateInputThreadSettings | None 140 "Configuration overrides for the thread, such as AI model selection and context window settings." 141 slug: str | None 142 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 143 title: str | None 144 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 145 visibility: Literal["team", "restricted", "private", "org"] | None 146 "Thread visibility. A team-owned thread with members must explicitly use `restricted` or `private`. User- and agent-owned threads with members default to `private` and reject every other value. `org` is only valid on an organization-owned thread with no team, user, or agent owner." 147 148 149class OrgThreadCreateInput(TypedDict, total=False): 150 "Create an organization-visibility thread" 151 152 skip_welcome_message: bool | None 153 "When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`." 154 thread: Required[OrgThreadCreateInputThread] 155 "Attributes for the new thread. Visibility is forced to `org`." 156 157 158class OrgTaskListResponseDataItemCreatedByActorProfilePicture(BaseModel): 159 file: str | None = Field( 160 default=None, 161 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 162 ) 163 height: int | None = Field( 164 default=None, description="Height of the image in pixels. `null` if not known." 165 ) 166 media: str | None = Field( 167 default=None, 168 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 169 ) 170 mime_type: str | None = Field( 171 default=None, 172 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 173 ) 174 refresh_url: str | None = Field( 175 default=None, 176 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.", 177 ) 178 url: str | None = Field( 179 default=None, 180 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.", 181 ) 182 width: int | None = Field( 183 default=None, description="Width of the image in pixels. `null` if not known." 184 ) 185 186 187class OrgTaskListResponseDataItemCreatedByActor(BaseModel): 188 alias: str | None = Field( 189 default=None, 190 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 191 ) 192 id: str | None = Field( 193 default=None, 194 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 195 ) 196 name: str | None = Field( 197 default=None, 198 description="Display name of the actor shown in the UI. `null` if no name is set.", 199 ) 200 profile_picture: OrgTaskListResponseDataItemCreatedByActorProfilePicture | None = Field( 201 default=None, 202 description="Profile picture for the actor. `null` if the actor has no profile picture.", 203 ) 204 205 206class OrgTaskListResponseDataItemCurrentLease(BaseModel): 207 expires_at: datetime = Field( 208 ..., description="Server-calculated lease expiry in ISO 8601 format." 209 ) 210 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 211 session_name: str = Field( 212 ..., description="Display name supplied by the coding session that holds the lease." 213 ) 214 215 216class OrgTaskListResponseDataItemOwnerActorProfilePicture(BaseModel): 217 file: str | None = Field( 218 default=None, 219 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 220 ) 221 height: int | None = Field( 222 default=None, description="Height of the image in pixels. `null` if not known." 223 ) 224 media: str | None = Field( 225 default=None, 226 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 227 ) 228 mime_type: str | None = Field( 229 default=None, 230 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 231 ) 232 refresh_url: str | None = Field( 233 default=None, 234 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.", 235 ) 236 url: str | None = Field( 237 default=None, 238 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.", 239 ) 240 width: int | None = Field( 241 default=None, description="Width of the image in pixels. `null` if not known." 242 ) 243 244 245class OrgTaskListResponseDataItemOwnerActor(BaseModel): 246 alias: str | None = Field( 247 default=None, 248 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 249 ) 250 id: str | None = Field( 251 default=None, 252 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 253 ) 254 name: str | None = Field( 255 default=None, 256 description="Display name of the actor shown in the UI. `null` if no name is set.", 257 ) 258 profile_picture: OrgTaskListResponseDataItemOwnerActorProfilePicture | None = Field( 259 default=None, 260 description="Profile picture for the actor. `null` if the actor has no profile picture.", 261 ) 262 263 264class OrgTaskListResponseDataItem(BaseModel): 265 agent: str | None = Field( 266 default=None, 267 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 268 ) 269 aggregate_version: int | None = Field( 270 default=None, 271 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 272 ) 273 blocked_by_count: int | None = Field( 274 default=None, 275 description="Number of readable 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.", 276 ) 277 closed_at: datetime | None = Field( 278 default=None, 279 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 280 ) 281 comments_count: int | None = Field( 282 default=None, description="Total number of comments posted on this task." 283 ) 284 created_at: datetime | None = Field( 285 default=None, description="When the task was created (ISO 8601)." 286 ) 287 created_by_actor: OrgTaskListResponseDataItemCreatedByActor | None = Field( 288 default=None, 289 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).", 290 ) 291 created_by_agent: str | None = Field( 292 default=None, 293 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.", 294 ) 295 created_by_user: str | None = Field( 296 default=None, 297 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.", 298 ) 299 current_lease: OrgTaskListResponseDataItemCurrentLease | None = Field( 300 default=None, 301 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.", 302 ) 303 description: str | None = Field( 304 default=None, 305 description="Long-form description or notes for the task. `null` if no description has been provided.", 306 ) 307 due_date: datetime | None = Field( 308 default=None, 309 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 310 ) 311 epic: str | None = Field( 312 default=None, 313 description="Free-form grouping label. `null` when the task is not in an epic.", 314 ) 315 id: str = Field(..., description="Task ID (`tsk_...`).") 316 is_blocked: bool | None = Field( 317 default=None, 318 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 reads, including mutation responses.", 319 ) 320 is_stalled: bool | None = Field( 321 default=None, 322 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 323 ) 324 links: dict[str, Any] | None = Field( 325 default=None, 326 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 327 ) 328 metadata: dict[str, Any] | None = Field( 329 default=None, 330 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 331 ) 332 name: str = Field(..., description="Human-readable title of the task.") 333 org: str | None = Field( 334 default=None, 335 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 336 ) 337 owner_actor: OrgTaskListResponseDataItemOwnerActor | None = Field( 338 default=None, 339 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).", 340 ) 341 owner_agent: str | None = Field( 342 default=None, 343 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.", 344 ) 345 owner_user: str | None = Field( 346 default=None, 347 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.", 348 ) 349 parent: str | None = Field( 350 default=None, 351 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 352 ) 353 priority: int | None = Field( 354 default=None, 355 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 356 ) 357 project_id: str | None = Field( 358 default=None, 359 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 360 ) 361 sandbox: str | None = Field( 362 default=None, 363 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 364 ) 365 source_id: str | None = Field( 366 default=None, 367 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 368 ) 369 source_scope: str | None = Field( 370 default=None, 371 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`.", 372 ) 373 source_type: str | None = Field( 374 default=None, 375 description="Kind of source object (for example `repository`). `null` when the task has no source.", 376 ) 377 stalled_since: datetime | None = Field( 378 default=None, 379 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 380 ) 381 status: str = Field( 382 ..., 383 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 384 ) 385 subtasks_count: int | None = Field( 386 default=None, 387 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 388 ) 389 tags: list[str] | None = Field( 390 default=None, 391 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 392 ) 393 target_binary: str | None = Field( 394 default=None, 395 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 396 ) 397 target_version: str | None = Field( 398 default=None, 399 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 400 ) 401 team: str | None = Field( 402 default=None, 403 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 404 ) 405 thread: str | None = Field( 406 default=None, 407 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.", 408 ) 409 updated_at: datetime | None = Field( 410 default=None, description="When the task was last modified (ISO 8601)." 411 ) 412 user: str | None = Field( 413 default=None, 414 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 415 ) 416 417 418class OrgTaskListResponse(BaseModel): 419 """ 420 Successful response 421 """ 422 423 after_cursor: str | None = None 424 before_cursor: str | None = None 425 data: list[OrgTaskListResponseDataItem] = Field( 426 ..., description="Array of task objects matching the requested filters." 427 ) 428 has_more: bool 429 430 431class OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(BaseModel): 432 file: str | None = Field( 433 default=None, 434 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 435 ) 436 height: int | None = Field( 437 default=None, description="Height of the image in pixels. `null` if not known." 438 ) 439 media: str | None = Field( 440 default=None, 441 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 442 ) 443 mime_type: str | None = Field( 444 default=None, 445 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 446 ) 447 refresh_url: str | None = Field( 448 default=None, 449 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.", 450 ) 451 url: str | None = Field( 452 default=None, 453 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.", 454 ) 455 width: int | None = Field( 456 default=None, description="Width of the image in pixels. `null` if not known." 457 ) 458 459 460class OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(BaseModel): 461 alias: str | None = Field( 462 default=None, 463 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 464 ) 465 id: str | None = Field( 466 default=None, 467 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 468 ) 469 name: str | None = Field( 470 default=None, 471 description="Display name of the actor shown in the UI. `null` if no name is set.", 472 ) 473 profile_picture: ( 474 OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None 475 ) = Field( 476 default=None, 477 description="Profile picture for the actor. `null` if the actor has no profile picture.", 478 ) 479 480 481class OrgTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(BaseModel): 482 expires_at: datetime = Field( 483 ..., description="Server-calculated lease expiry in ISO 8601 format." 484 ) 485 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 486 session_name: str = Field( 487 ..., description="Display name supplied by the coding session that holds the lease." 488 ) 489 490 491class OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(BaseModel): 492 file: str | None = Field( 493 default=None, 494 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 495 ) 496 height: int | None = Field( 497 default=None, description="Height of the image in pixels. `null` if not known." 498 ) 499 media: str | None = Field( 500 default=None, 501 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 502 ) 503 mime_type: str | None = Field( 504 default=None, 505 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 506 ) 507 refresh_url: str | None = Field( 508 default=None, 509 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.", 510 ) 511 url: str | None = Field( 512 default=None, 513 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.", 514 ) 515 width: int | None = Field( 516 default=None, description="Width of the image in pixels. `null` if not known." 517 ) 518 519 520class OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(BaseModel): 521 alias: str | None = Field( 522 default=None, 523 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 524 ) 525 id: str | None = Field( 526 default=None, 527 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 528 ) 529 name: str | None = Field( 530 default=None, 531 description="Display name of the actor shown in the UI. `null` if no name is set.", 532 ) 533 profile_picture: ( 534 OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None 535 ) = Field( 536 default=None, 537 description="Profile picture for the actor. `null` if the actor has no profile picture.", 538 ) 539 540 541class OrgTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): 542 agent: str | None = Field( 543 default=None, 544 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 545 ) 546 aggregate_version: int | None = Field( 547 default=None, 548 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 549 ) 550 blocked_by_count: int | None = Field( 551 default=None, 552 description="Number of readable 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.", 553 ) 554 closed_at: datetime | None = Field( 555 default=None, 556 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 557 ) 558 comments_count: int | None = Field( 559 default=None, description="Total number of comments posted on this task." 560 ) 561 created_at: datetime | None = Field( 562 default=None, description="When the task was created (ISO 8601)." 563 ) 564 created_by_actor: OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor | None = Field( 565 default=None, 566 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).", 567 ) 568 created_by_agent: str | None = Field( 569 default=None, 570 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.", 571 ) 572 created_by_user: str | None = Field( 573 default=None, 574 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.", 575 ) 576 current_lease: OrgTaskBlockerCyclesResponseDataItemTasksItemCurrentLease | None = Field( 577 default=None, 578 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.", 579 ) 580 description: str | None = Field( 581 default=None, 582 description="Long-form description or notes for the task. `null` if no description has been provided.", 583 ) 584 due_date: datetime | None = Field( 585 default=None, 586 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 587 ) 588 epic: str | None = Field( 589 default=None, 590 description="Free-form grouping label. `null` when the task is not in an epic.", 591 ) 592 id: str = Field(..., description="Task ID (`tsk_...`).") 593 is_blocked: bool | None = Field( 594 default=None, 595 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 reads, including mutation responses.", 596 ) 597 is_stalled: bool | None = Field( 598 default=None, 599 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 600 ) 601 links: dict[str, Any] | None = Field( 602 default=None, 603 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 604 ) 605 metadata: dict[str, Any] | None = Field( 606 default=None, 607 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 608 ) 609 name: str = Field(..., description="Human-readable title of the task.") 610 org: str | None = Field( 611 default=None, 612 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 613 ) 614 owner_actor: OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActor | None = Field( 615 default=None, 616 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).", 617 ) 618 owner_agent: str | None = Field( 619 default=None, 620 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.", 621 ) 622 owner_user: str | None = Field( 623 default=None, 624 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.", 625 ) 626 parent: str | None = Field( 627 default=None, 628 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 629 ) 630 priority: int | None = Field( 631 default=None, 632 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 633 ) 634 project_id: str | None = Field( 635 default=None, 636 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 637 ) 638 sandbox: str | None = Field( 639 default=None, 640 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 641 ) 642 source_id: str | None = Field( 643 default=None, 644 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 645 ) 646 source_scope: str | None = Field( 647 default=None, 648 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`.", 649 ) 650 source_type: str | None = Field( 651 default=None, 652 description="Kind of source object (for example `repository`). `null` when the task has no source.", 653 ) 654 stalled_since: datetime | None = Field( 655 default=None, 656 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 657 ) 658 status: str = Field( 659 ..., 660 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 661 ) 662 subtasks_count: int | None = Field( 663 default=None, 664 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 665 ) 666 tags: list[str] | None = Field( 667 default=None, 668 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 669 ) 670 target_binary: str | None = Field( 671 default=None, 672 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 673 ) 674 target_version: str | None = Field( 675 default=None, 676 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 677 ) 678 team: str | None = Field( 679 default=None, 680 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 681 ) 682 thread: str | None = Field( 683 default=None, 684 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.", 685 ) 686 updated_at: datetime | None = Field( 687 default=None, description="When the task was last modified (ISO 8601)." 688 ) 689 user: str | None = Field( 690 default=None, 691 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 692 ) 693 694 695class OrgTaskBlockerCyclesResponseDataItem(BaseModel): 696 tasks: list[OrgTaskBlockerCyclesResponseDataItemTasksItem] = Field( 697 ..., description="Every unfinished task in this cyclic blocker component." 698 ) 699 700 701class OrgTaskBlockerCyclesResponse(BaseModel): 702 """ 703 Successful response 704 """ 705 706 after_cursor: str | None = None 707 before_cursor: str | None = None 708 data: list[OrgTaskBlockerCyclesResponseDataItem] 709 has_more: bool 710 711 712class OrgTaskMetricsResponse(BaseModel): 713 """ 714 Successful response 715 """ 716 717 completed: int 718 created: int 719 days: int 720 end_at: datetime 721 open: int 722 series: list[dict[str, Any]] = Field( 723 ..., 724 description="Zero-filled UTC-day buckets with `date`, end-of-day `open`, `created`, and `completed`.", 725 ) 726 start_at: datetime 727 728 729class OrgTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): 730 file: str | None = Field( 731 default=None, 732 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 733 ) 734 height: int | None = Field( 735 default=None, description="Height of the image in pixels. `null` if not known." 736 ) 737 media: str | None = Field( 738 default=None, 739 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 740 ) 741 mime_type: str | None = Field( 742 default=None, 743 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 744 ) 745 refresh_url: str | None = Field( 746 default=None, 747 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.", 748 ) 749 url: str | None = Field( 750 default=None, 751 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.", 752 ) 753 width: int | None = Field( 754 default=None, description="Width of the image in pixels. `null` if not known." 755 ) 756 757 758class OrgTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): 759 alias: str | None = Field( 760 default=None, 761 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 762 ) 763 id: str | None = Field( 764 default=None, 765 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 766 ) 767 name: str | None = Field( 768 default=None, 769 description="Display name of the actor shown in the UI. `null` if no name is set.", 770 ) 771 profile_picture: OrgTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( 772 default=None, 773 description="Profile picture for the actor. `null` if the actor has no profile picture.", 774 ) 775 776 777class OrgTaskReadyResponseDataItemTaskCurrentLease(BaseModel): 778 expires_at: datetime = Field( 779 ..., description="Server-calculated lease expiry in ISO 8601 format." 780 ) 781 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 782 session_name: str = Field( 783 ..., description="Display name supplied by the coding session that holds the lease." 784 ) 785 786 787class OrgTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): 788 file: str | None = Field( 789 default=None, 790 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 791 ) 792 height: int | None = Field( 793 default=None, description="Height of the image in pixels. `null` if not known." 794 ) 795 media: str | None = Field( 796 default=None, 797 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 798 ) 799 mime_type: str | None = Field( 800 default=None, 801 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 802 ) 803 refresh_url: str | None = Field( 804 default=None, 805 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.", 806 ) 807 url: str | None = Field( 808 default=None, 809 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.", 810 ) 811 width: int | None = Field( 812 default=None, description="Width of the image in pixels. `null` if not known." 813 ) 814 815 816class OrgTaskReadyResponseDataItemTaskOwnerActor(BaseModel): 817 alias: str | None = Field( 818 default=None, 819 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 820 ) 821 id: str | None = Field( 822 default=None, 823 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 824 ) 825 name: str | None = Field( 826 default=None, 827 description="Display name of the actor shown in the UI. `null` if no name is set.", 828 ) 829 profile_picture: OrgTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( 830 default=None, 831 description="Profile picture for the actor. `null` if the actor has no profile picture.", 832 ) 833 834 835class OrgTaskReadyResponseDataItemTask(BaseModel): 836 agent: str | None = Field( 837 default=None, 838 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 839 ) 840 aggregate_version: int | None = Field( 841 default=None, 842 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 843 ) 844 blocked_by_count: int | None = Field( 845 default=None, 846 description="Number of readable 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.", 847 ) 848 closed_at: datetime | None = Field( 849 default=None, 850 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 851 ) 852 comments_count: int | None = Field( 853 default=None, description="Total number of comments posted on this task." 854 ) 855 created_at: datetime | None = Field( 856 default=None, description="When the task was created (ISO 8601)." 857 ) 858 created_by_actor: OrgTaskReadyResponseDataItemTaskCreatedByActor | None = Field( 859 default=None, 860 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).", 861 ) 862 created_by_agent: str | None = Field( 863 default=None, 864 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.", 865 ) 866 created_by_user: str | None = Field( 867 default=None, 868 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.", 869 ) 870 current_lease: OrgTaskReadyResponseDataItemTaskCurrentLease | None = Field( 871 default=None, 872 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.", 873 ) 874 description: str | None = Field( 875 default=None, 876 description="Long-form description or notes for the task. `null` if no description has been provided.", 877 ) 878 due_date: datetime | None = Field( 879 default=None, 880 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 881 ) 882 epic: str | None = Field( 883 default=None, 884 description="Free-form grouping label. `null` when the task is not in an epic.", 885 ) 886 id: str = Field(..., description="Task ID (`tsk_...`).") 887 is_blocked: bool | None = Field( 888 default=None, 889 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 reads, including mutation responses.", 890 ) 891 is_stalled: bool | None = Field( 892 default=None, 893 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 894 ) 895 links: dict[str, Any] | None = Field( 896 default=None, 897 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 898 ) 899 metadata: dict[str, Any] | None = Field( 900 default=None, 901 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 902 ) 903 name: str = Field(..., description="Human-readable title of the task.") 904 org: str | None = Field( 905 default=None, 906 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 907 ) 908 owner_actor: OrgTaskReadyResponseDataItemTaskOwnerActor | None = Field( 909 default=None, 910 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).", 911 ) 912 owner_agent: str | None = Field( 913 default=None, 914 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.", 915 ) 916 owner_user: str | None = Field( 917 default=None, 918 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.", 919 ) 920 parent: str | None = Field( 921 default=None, 922 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 923 ) 924 priority: int | None = Field( 925 default=None, 926 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 927 ) 928 project_id: str | None = Field( 929 default=None, 930 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 931 ) 932 sandbox: str | None = Field( 933 default=None, 934 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 935 ) 936 source_id: str | None = Field( 937 default=None, 938 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 939 ) 940 source_scope: str | None = Field( 941 default=None, 942 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`.", 943 ) 944 source_type: str | None = Field( 945 default=None, 946 description="Kind of source object (for example `repository`). `null` when the task has no source.", 947 ) 948 stalled_since: datetime | None = Field( 949 default=None, 950 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 951 ) 952 status: str = Field( 953 ..., 954 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 955 ) 956 subtasks_count: int | None = Field( 957 default=None, 958 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 959 ) 960 tags: list[str] | None = Field( 961 default=None, 962 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 963 ) 964 target_binary: str | None = Field( 965 default=None, 966 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 967 ) 968 target_version: str | None = Field( 969 default=None, 970 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 971 ) 972 team: str | None = Field( 973 default=None, 974 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 975 ) 976 thread: str | None = Field( 977 default=None, 978 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.", 979 ) 980 updated_at: datetime | None = Field( 981 default=None, description="When the task was last modified (ISO 8601)." 982 ) 983 user: str | None = Field( 984 default=None, 985 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 986 ) 987 988 989class OrgTaskReadyResponseDataItem(BaseModel): 990 readiness: Literal["ready", "blocked", "leased"] = Field( 991 ..., description="One of `ready`, `blocked`, or `leased`." 992 ) 993 reason: Literal["open_blockers", "active_lease"] | None = Field( 994 default=None, 995 description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", 996 ) 997 task: OrgTaskReadyResponseDataItemTask = Field( 998 ..., description="The task evaluated for readiness." 999 ) 1000 1001 1002class OrgTaskReadyResponse(BaseModel): 1003 """ 1004 Successful response 1005 """ 1006 1007 after_cursor: str | None = None 1008 authoritative: bool = Field( 1009 ..., 1010 description="Always false because projections can lag writes and a later claim can race this read.", 1011 ) 1012 before_cursor: str | None = None 1013 data: list[OrgTaskReadyResponseDataItem] 1014 has_more: bool 1015 1016 1017class OrgTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): 1018 file: str | None = Field( 1019 default=None, 1020 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1021 ) 1022 height: int | None = Field( 1023 default=None, description="Height of the image in pixels. `null` if not known." 1024 ) 1025 media: str | None = Field( 1026 default=None, 1027 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1028 ) 1029 mime_type: str | None = Field( 1030 default=None, 1031 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1032 ) 1033 refresh_url: str | None = Field( 1034 default=None, 1035 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.", 1036 ) 1037 url: str | None = Field( 1038 default=None, 1039 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.", 1040 ) 1041 width: int | None = Field( 1042 default=None, description="Width of the image in pixels. `null` if not known." 1043 ) 1044 1045 1046class OrgTaskSearchResponseDataItemCreatedByActor(BaseModel): 1047 alias: str | None = Field( 1048 default=None, 1049 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1050 ) 1051 id: str | None = Field( 1052 default=None, 1053 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1054 ) 1055 name: str | None = Field( 1056 default=None, 1057 description="Display name of the actor shown in the UI. `null` if no name is set.", 1058 ) 1059 profile_picture: OrgTaskSearchResponseDataItemCreatedByActorProfilePicture | None = Field( 1060 default=None, 1061 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1062 ) 1063 1064 1065class OrgTaskSearchResponseDataItemCurrentLease(BaseModel): 1066 expires_at: datetime = Field( 1067 ..., description="Server-calculated lease expiry in ISO 8601 format." 1068 ) 1069 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 1070 session_name: str = Field( 1071 ..., description="Display name supplied by the coding session that holds the lease." 1072 ) 1073 1074 1075class OrgTaskSearchResponseDataItemOwnerActorProfilePicture(BaseModel): 1076 file: str | None = Field( 1077 default=None, 1078 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1079 ) 1080 height: int | None = Field( 1081 default=None, description="Height of the image in pixels. `null` if not known." 1082 ) 1083 media: str | None = Field( 1084 default=None, 1085 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1086 ) 1087 mime_type: str | None = Field( 1088 default=None, 1089 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1090 ) 1091 refresh_url: str | None = Field( 1092 default=None, 1093 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.", 1094 ) 1095 url: str | None = Field( 1096 default=None, 1097 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.", 1098 ) 1099 width: int | None = Field( 1100 default=None, description="Width of the image in pixels. `null` if not known." 1101 ) 1102 1103 1104class OrgTaskSearchResponseDataItemOwnerActor(BaseModel): 1105 alias: str | None = Field( 1106 default=None, 1107 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1108 ) 1109 id: str | None = Field( 1110 default=None, 1111 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1112 ) 1113 name: str | None = Field( 1114 default=None, 1115 description="Display name of the actor shown in the UI. `null` if no name is set.", 1116 ) 1117 profile_picture: OrgTaskSearchResponseDataItemOwnerActorProfilePicture | None = Field( 1118 default=None, 1119 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1120 ) 1121 1122 1123class OrgTaskSearchResponseDataItem(BaseModel): 1124 agent: str | None = Field( 1125 default=None, 1126 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 1127 ) 1128 aggregate_version: int | None = Field( 1129 default=None, 1130 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 1131 ) 1132 blocked_by_count: int | None = Field( 1133 default=None, 1134 description="Number of readable 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.", 1135 ) 1136 closed_at: datetime | None = Field( 1137 default=None, 1138 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 1139 ) 1140 comments_count: int | None = Field( 1141 default=None, description="Total number of comments posted on this task." 1142 ) 1143 created_at: datetime | None = Field( 1144 default=None, description="When the task was created (ISO 8601)." 1145 ) 1146 created_by_actor: OrgTaskSearchResponseDataItemCreatedByActor | None = Field( 1147 default=None, 1148 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).", 1149 ) 1150 created_by_agent: str | None = Field( 1151 default=None, 1152 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.", 1153 ) 1154 created_by_user: str | None = Field( 1155 default=None, 1156 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.", 1157 ) 1158 current_lease: OrgTaskSearchResponseDataItemCurrentLease | None = Field( 1159 default=None, 1160 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.", 1161 ) 1162 description: str | None = Field( 1163 default=None, 1164 description="Long-form description or notes for the task. `null` if no description has been provided.", 1165 ) 1166 due_date: datetime | None = Field( 1167 default=None, 1168 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 1169 ) 1170 epic: str | None = Field( 1171 default=None, 1172 description="Free-form grouping label. `null` when the task is not in an epic.", 1173 ) 1174 id: str = Field(..., description="Task ID (`tsk_...`).") 1175 is_blocked: bool | None = Field( 1176 default=None, 1177 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 reads, including mutation responses.", 1178 ) 1179 is_stalled: bool | None = Field( 1180 default=None, 1181 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 1182 ) 1183 links: dict[str, Any] | None = Field( 1184 default=None, 1185 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 1186 ) 1187 metadata: dict[str, Any] | None = Field( 1188 default=None, 1189 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 1190 ) 1191 name: str = Field(..., description="Human-readable title of the task.") 1192 org: str | None = Field( 1193 default=None, 1194 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 1195 ) 1196 owner_actor: OrgTaskSearchResponseDataItemOwnerActor | None = Field( 1197 default=None, 1198 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).", 1199 ) 1200 owner_agent: str | None = Field( 1201 default=None, 1202 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.", 1203 ) 1204 owner_user: str | None = Field( 1205 default=None, 1206 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.", 1207 ) 1208 parent: str | None = Field( 1209 default=None, 1210 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 1211 ) 1212 priority: int | None = Field( 1213 default=None, 1214 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1215 ) 1216 project_id: str | None = Field( 1217 default=None, 1218 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 1219 ) 1220 sandbox: str | None = Field( 1221 default=None, 1222 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1223 ) 1224 source_id: str | None = Field( 1225 default=None, 1226 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1227 ) 1228 source_scope: str | None = Field( 1229 default=None, 1230 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`.", 1231 ) 1232 source_type: str | None = Field( 1233 default=None, 1234 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1235 ) 1236 stalled_since: datetime | None = Field( 1237 default=None, 1238 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 1239 ) 1240 status: str = Field( 1241 ..., 1242 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 1243 ) 1244 subtasks_count: int | None = Field( 1245 default=None, 1246 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1247 ) 1248 tags: list[str] | None = Field( 1249 default=None, 1250 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1251 ) 1252 target_binary: str | None = Field( 1253 default=None, 1254 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 1255 ) 1256 target_version: str | None = Field( 1257 default=None, 1258 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 1259 ) 1260 team: str | None = Field( 1261 default=None, 1262 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1263 ) 1264 thread: str | None = Field( 1265 default=None, 1266 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.", 1267 ) 1268 updated_at: datetime | None = Field( 1269 default=None, description="When the task was last modified (ISO 8601)." 1270 ) 1271 user: str | None = Field( 1272 default=None, 1273 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1274 ) 1275 1276 1277class OrgTaskSearchResponse(BaseModel): 1278 """ 1279 Successful response 1280 """ 1281 1282 after_cursor: str | None = None 1283 before_cursor: str | None = None 1284 data: list[OrgTaskSearchResponseDataItem] = Field( 1285 ..., description="Array of task objects matching the query and filters." 1286 ) 1287 has_more: bool 1288 query: str 1289 1290 1291class OrgThreadListResponseDataItemParentMessageAclAddItem(BaseModel): 1292 actions: list[str] = Field( 1293 ..., 1294 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1295 ) 1296 principal: str | None = Field( 1297 default=None, 1298 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1299 ) 1300 principal_type: str = Field( 1301 ..., 1302 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1303 ) 1304 1305 1306class OrgThreadListResponseDataItemParentMessageAclGrantsItem(BaseModel): 1307 actions: list[str] = Field( 1308 ..., 1309 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1310 ) 1311 principal: str | None = Field( 1312 default=None, 1313 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1314 ) 1315 principal_type: str = Field( 1316 ..., 1317 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1318 ) 1319 1320 1321class OrgThreadListResponseDataItemParentMessageAclRemoveItem(BaseModel): 1322 principal: str | None = Field( 1323 default=None, 1324 description='The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.', 1325 ) 1326 principal_type: str = Field( 1327 ..., 1328 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1329 ) 1330 1331 1332class OrgThreadListResponseDataItemParentMessageAcl(BaseModel): 1333 add: list[OrgThreadListResponseDataItemParentMessageAclAddItem] | None = Field( 1334 default=None, 1335 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1336 ) 1337 grants: list[OrgThreadListResponseDataItemParentMessageAclGrantsItem] | None = Field( 1338 default=None, 1339 description="Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", 1340 ) 1341 remove: list[OrgThreadListResponseDataItemParentMessageAclRemoveItem] | None = Field( 1342 default=None, 1343 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1344 ) 1345 1346 1347class OrgThreadListResponseDataItemParentMessageActorsItemProfilePicture(BaseModel): 1348 file: str | None = Field( 1349 default=None, 1350 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1351 ) 1352 height: int | None = Field( 1353 default=None, description="Height of the image in pixels. `null` if not known." 1354 ) 1355 media: str | None = Field( 1356 default=None, 1357 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1358 ) 1359 mime_type: str | None = Field( 1360 default=None, 1361 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1362 ) 1363 refresh_url: str | None = Field( 1364 default=None, 1365 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.", 1366 ) 1367 url: str | None = Field( 1368 default=None, 1369 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.", 1370 ) 1371 width: int | None = Field( 1372 default=None, description="Width of the image in pixels. `null` if not known." 1373 ) 1374 1375 1376class OrgThreadListResponseDataItemParentMessageActorsItem(BaseModel): 1377 alias: str | None = Field( 1378 default=None, 1379 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1380 ) 1381 id: str | None = Field( 1382 default=None, 1383 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1384 ) 1385 name: str | None = Field( 1386 default=None, 1387 description="Display name of the actor shown in the UI. `null` if no name is set.", 1388 ) 1389 profile_picture: OrgThreadListResponseDataItemParentMessageActorsItemProfilePicture | None = ( 1390 Field( 1391 default=None, 1392 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1393 ) 1394 ) 1395 1396 1397class OrgThreadListResponseDataItemParentMessageAttachmentsItemImageSource(BaseModel): 1398 file: str | None = Field( 1399 default=None, 1400 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1401 ) 1402 height: int | None = Field( 1403 default=None, description="Height of the image in pixels. `null` if not known." 1404 ) 1405 media: str | None = Field( 1406 default=None, 1407 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1408 ) 1409 mime_type: str | None = Field( 1410 default=None, 1411 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1412 ) 1413 refresh_url: str | None = Field( 1414 default=None, 1415 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.", 1416 ) 1417 url: str | None = Field( 1418 default=None, 1419 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.", 1420 ) 1421 width: int | None = Field( 1422 default=None, description="Width of the image in pixels. `null` if not known." 1423 ) 1424 1425 1426class OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(BaseModel): 1427 file: str | None = Field( 1428 default=None, 1429 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1430 ) 1431 height: int | None = Field( 1432 default=None, description="Height of the image in pixels. `null` if not known." 1433 ) 1434 media: str | None = Field( 1435 default=None, 1436 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1437 ) 1438 mime_type: str | None = Field( 1439 default=None, 1440 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1441 ) 1442 refresh_url: str | None = Field( 1443 default=None, 1444 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.", 1445 ) 1446 url: str | None = Field( 1447 default=None, 1448 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.", 1449 ) 1450 width: int | None = Field( 1451 default=None, description="Width of the image in pixels. `null` if not known." 1452 ) 1453 1454 1455class OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(BaseModel): 1456 byte_size: int | None = Field(default=None, description="Size of the stored bytes.") 1457 content_type: str | None = Field( 1458 default=None, 1459 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 1460 ) 1461 created_at: datetime | None = Field( 1462 default=None, description="When this variant was created (ISO 8601)." 1463 ) 1464 duration_ms: int | None = Field( 1465 default=None, 1466 description="Client-declared video duration in milliseconds; not server-probed.", 1467 ) 1468 file: str | None = Field( 1469 default=None, 1470 description="ID of the underlying storage file that backs this variant (`fil_...`).", 1471 ) 1472 filename: str | None = Field( 1473 default=None, 1474 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 1475 ) 1476 height: int | None = Field( 1477 default=None, description="Height of this variant in pixels. `null` if not recorded." 1478 ) 1479 id: str = Field(..., description="Media variant ID (`mvr_...`).") 1480 image_source: ( 1481 OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | None 1482 ) = Field( 1483 default=None, 1484 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 1485 ) 1486 sha256: str | None = Field(default=None, description="Lowercase SHA-256 of the stored bytes.") 1487 updated_at: datetime | None = Field( 1488 default=None, description="When this variant was last updated (ISO 8601)." 1489 ) 1490 url: str | None = Field( 1491 default=None, 1492 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 1493 ) 1494 url_expires_at: datetime | None = Field( 1495 default=None, description="Expiry of this variant's playable URL." 1496 ) 1497 variant_key: str | None = Field( 1498 default=None, 1499 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 1500 ) 1501 width: int | None = Field( 1502 default=None, description="Width of this variant in pixels. `null` if not recorded." 1503 ) 1504 1505 1506class OrgThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): 1507 content_type: str | None = Field( 1508 default=None, 1509 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1510 ) 1511 description: str | None = Field( 1512 default=None, 1513 description="Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types.", 1514 ) 1515 filename: str | None = Field( 1516 default=None, 1517 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1518 ) 1519 height: int | None = Field( 1520 default=None, 1521 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 1522 ) 1523 id: str = Field(..., description="Unique identifier for this attachment within the message.") 1524 image_height: int | None = Field( 1525 default=None, 1526 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1527 ) 1528 image_source: OrgThreadListResponseDataItemParentMessageAttachmentsItemImageSource | None = ( 1529 Field( 1530 default=None, 1531 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 1532 ) 1533 ) 1534 image_url: str | None = Field( 1535 default=None, 1536 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 1537 ) 1538 image_width: int | None = Field( 1539 default=None, 1540 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1541 ) 1542 key: str | None = Field( 1543 default=None, 1544 description='For `structured_data` type, what the data is about as set by the sender (for example `"pr:14963"`), copied from the record so it can be read without `object`. Not unique. `null` when unset and on other types.', 1545 ) 1546 media_type: str | None = Field( 1547 default=None, 1548 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 1549 ) 1550 name: str | None = Field( 1551 default=None, 1552 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 1553 ) 1554 object: dict[str, Any] | None = Field( 1555 default=None, 1556 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. For `structured_data` type, contains the inline `data` and the `schema_url` or `schema_config` naming its JSON Schema. Omitted on other types.", 1557 ) 1558 title: str | None = Field( 1559 default=None, 1560 description="Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types.", 1561 ) 1562 type: str = Field( 1563 ..., 1564 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, `"chart"`, or `"structured_data"`. Determines which additional fields are present.', 1565 ) 1566 url: str | None = Field( 1567 default=None, 1568 description="URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types.", 1569 ) 1570 variants: list[OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None = ( 1571 Field( 1572 default=None, 1573 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 1574 ) 1575 ) 1576 version: int | None = Field( 1577 default=None, 1578 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 1579 ) 1580 width: int | None = Field( 1581 default=None, 1582 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 1583 ) 1584 1585 1586class OrgThreadListResponseDataItemParentMessageContextItem(BaseModel): 1587 attributes: dict[str, Any] | None = Field( 1588 default=None, 1589 description="Scalar key-value fields describing the context, such as route, repository, or pull-request number.", 1590 ) 1591 content: str | None = Field( 1592 default=None, 1593 description="Optional context body. The model receives it as escaped XML data, not a system instruction.", 1594 ) 1595 title: str | None = Field( 1596 default=None, description="Optional human-readable label for this context block." 1597 ) 1598 type: str = Field( 1599 ..., 1600 description="Stable context kind. Must start with a lowercase letter and contain only lowercase letters, numbers, dots, dashes, or underscores.", 1601 ) 1602 1603 1604class OrgThreadListResponseDataItemParentMessageReactionsItem(BaseModel): 1605 payload: dict[str, Any] | None = Field( 1606 default=None, 1607 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 1608 ) 1609 type: str = Field( 1610 ..., 1611 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 1612 ) 1613 user: str | None = Field( 1614 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 1615 ) 1616 1617 1618class OrgThreadListResponseDataItemParentMessage(BaseModel): 1619 acl: OrgThreadListResponseDataItemParentMessageAcl | None = Field( 1620 default=None, 1621 description="Access control list for private messages (grants with `read` action). Only returned to resource owners (and privileged/org-admin viewers) via server-side `field_redactions: [acl: :owner]`; `null` for everyone else.", 1622 ) 1623 actors: list[OrgThreadListResponseDataItemParentMessageActorsItem] | None = Field( 1624 default=None, 1625 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 1626 ) 1627 agent: str | None = Field( 1628 default=None, 1629 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 1630 ) 1631 agent_mode: Literal["cli", "embedded"] | None = Field( 1632 default=None, 1633 description="Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path.", 1634 ) 1635 attachments: list[OrgThreadListResponseDataItemParentMessageAttachmentsItem] | None = Field( 1636 default=None, 1637 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 1638 ) 1639 branched_thread: str | None = Field( 1640 default=None, 1641 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 1642 ) 1643 content: str | None = Field( 1644 default=None, 1645 description="Text content of the message. `null` for messages that contain only attachments.", 1646 ) 1647 context: list[OrgThreadListResponseDataItemParentMessageContextItem] | None = Field( 1648 default=None, 1649 description="Immutable structured context captured when the message was posted. Each entry has `type`, optional `title` and `content`, and scalar `attributes`. Always present; defaults to an empty array. Context is delivered to agents as escaped XML data, not as system instructions.", 1650 ) 1651 created_at: str | None = Field( 1652 default=None, description="When the message was posted (ISO 8601)." 1653 ) 1654 has_replies: bool | None = Field( 1655 default=None, 1656 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 1657 ) 1658 id: str = Field(..., description="Message ID (`msg_...`).") 1659 idempotency_key: str | None = Field( 1660 default=None, 1661 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 1662 ) 1663 is_deleted: bool | None = Field( 1664 default=None, 1665 description="Whether this message is a deletion tombstone. `true` only on the `message_updated` broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always `false` for live messages.", 1666 ) 1667 legacy_agent: str | None = Field( 1668 default=None, 1669 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 1670 ) 1671 metadata: dict[str, Any] | None = Field( 1672 default=None, 1673 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 1674 ) 1675 org: str | None = Field( 1676 default=None, description="ID of the organization that owns this message (`org_...`)." 1677 ) 1678 reactions: list[OrgThreadListResponseDataItemParentMessageReactionsItem] | None = Field( 1679 default=None, 1680 description="Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded.", 1681 ) 1682 rendering_mode: str | None = Field( 1683 default=None, 1684 description='Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.', 1685 ) 1686 replies: list[dict[str, Any]] | None = Field( 1687 default=None, 1688 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 1689 ) 1690 replies_after_cursor: str | None = Field( 1691 default=None, 1692 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 1693 ) 1694 replies_before_cursor: str | None = Field( 1695 default=None, 1696 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 1697 ) 1698 reply_count: int | None = Field( 1699 default=None, 1700 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 1701 ) 1702 reply_to: dict[str, Any] | None = Field( 1703 default=None, 1704 description="The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded.", 1705 ) 1706 root_message_id: str | None = Field( 1707 default=None, 1708 description="ID of the root message in this reply chain (`msg_...`). `null` for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages.", 1709 ) 1710 sandbox: str | None = Field( 1711 default=None, 1712 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 1713 ) 1714 team: str | None = Field( 1715 default=None, 1716 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 1717 ) 1718 thread: str | None = Field( 1719 default=None, description="ID of the thread this message belongs to (`thr_...`)." 1720 ) 1721 type: str | None = Field( 1722 default=None, 1723 description="Optional client-defined classification for the message (for example `note` or `status`). Free-form string up to 64 characters. The value `system` is reserved for platform-authored messages and cannot be set by clients. `null` when unset.", 1724 ) 1725 user: str | dict[str, Any] | None = Field( 1726 default=None, 1727 description="The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents.", 1728 ) 1729 visibility: Literal["default", "private"] | None = Field( 1730 default=None, 1731 description="Message-level visibility. `default` is visible to anyone who can see the parent thread. `private` is restricted to the sender and explicit ACL `read` grantees.", 1732 ) 1733 1734 1735class OrgThreadListResponseDataItemParticipantsItem(BaseModel): 1736 alias: str | None = Field( 1737 default=None, description="Short handle or alias for the user. `null` if not set." 1738 ) 1739 app: str | None = Field( 1740 default=None, 1741 description="ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.", 1742 ) 1743 app_name: str | None = Field( 1744 default=None, 1745 description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", 1746 ) 1747 created_by_agent_user: str | None = Field( 1748 default=None, 1749 description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", 1750 ) 1751 created_by_developer: str | None = Field( 1752 default=None, 1753 description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", 1754 ) 1755 created_by_org: str | None = Field( 1756 default=None, 1757 description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", 1758 ) 1759 created_by_team: str | None = Field( 1760 default=None, 1761 description="Team that created this user (`tem_...`). `null` unless created as a team.", 1762 ) 1763 created_by_user: str | None = Field( 1764 default=None, 1765 description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", 1766 ) 1767 email: str | None = Field(default=None, description="Email address of the user.") 1768 id: str = Field(..., description="User ID (`usr_...`).") 1769 is_system_user: bool | None = Field( 1770 default=None, 1771 description="`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", 1772 ) 1773 metadata: dict[str, Any] | None = Field( 1774 default=None, 1775 description="Arbitrary key-value metadata attached to the user. Defaults to an empty object.", 1776 ) 1777 name: str | None = Field( 1778 default=None, 1779 description="Full display name of the user. `null` if the user has not set a name.", 1780 ) 1781 org: str | None = Field( 1782 default=None, 1783 description="ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", 1784 ) 1785 org_name: str | None = Field( 1786 default=None, 1787 description="Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.", 1788 ) 1789 org_role: str | None = Field( 1790 default=None, 1791 description='Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.', 1792 ) 1793 org_slug: str | None = Field( 1794 default=None, 1795 description="Stable workspace slug for the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.", 1796 ) 1797 sandbox: str | None = Field( 1798 default=None, 1799 description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", 1800 ) 1801 sandbox_name: str | None = Field( 1802 default=None, 1803 description="Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", 1804 ) 1805 1806 1807class OrgThreadListResponseDataItemParticipatingAgentsItemAclAddItem(BaseModel): 1808 actions: list[str] = Field( 1809 ..., 1810 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1811 ) 1812 principal: str | None = Field( 1813 default=None, 1814 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1815 ) 1816 principal_type: str = Field( 1817 ..., 1818 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1819 ) 1820 1821 1822class OrgThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(BaseModel): 1823 actions: list[str] = Field( 1824 ..., 1825 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1826 ) 1827 principal: str | None = Field( 1828 default=None, 1829 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1830 ) 1831 principal_type: str = Field( 1832 ..., 1833 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1834 ) 1835 1836 1837class OrgThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(BaseModel): 1838 principal: str | None = Field( 1839 default=None, 1840 description='The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.', 1841 ) 1842 principal_type: str = Field( 1843 ..., 1844 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1845 ) 1846 1847 1848class OrgThreadListResponseDataItemParticipatingAgentsItemAcl(BaseModel): 1849 add: list[OrgThreadListResponseDataItemParticipatingAgentsItemAclAddItem] | None = Field( 1850 default=None, 1851 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1852 ) 1853 grants: list[OrgThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem] | None = Field( 1854 default=None, 1855 description="Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", 1856 ) 1857 remove: list[OrgThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem] | None = Field( 1858 default=None, 1859 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1860 ) 1861 1862 1863class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo( 1864 BaseModel 1865): 1866 file: str | None = Field( 1867 default=None, 1868 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1869 ) 1870 height: int | None = Field( 1871 default=None, description="Height of the image in pixels. `null` if not known." 1872 ) 1873 media: str | None = Field( 1874 default=None, 1875 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1876 ) 1877 mime_type: str | None = Field( 1878 default=None, 1879 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1880 ) 1881 refresh_url: str | None = Field( 1882 default=None, 1883 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.", 1884 ) 1885 url: str | None = Field( 1886 default=None, 1887 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.", 1888 ) 1889 width: int | None = Field( 1890 default=None, description="Width of the image in pixels. `null` if not known." 1891 ) 1892 1893 1894class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 1895 BaseModel 1896): 1897 description: str | None = Field( 1898 default=None, 1899 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 1900 ) 1901 name: str = Field( 1902 ..., 1903 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 1904 ) 1905 required: bool = Field( 1906 ..., 1907 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 1908 ) 1909 type: str = Field( 1910 ..., 1911 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 1912 ) 1913 1914 1915class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills( 1916 BaseModel 1917): 1918 participants: dict[str, Any] | None = Field( 1919 default=None, 1920 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 1921 ) 1922 payload: dict[str, Any] | None = Field( 1923 default=None, 1924 description="Partial invocation payload applied by the platform. A caller may omit these values, but supplying a different value at any locked path is rejected.", 1925 ) 1926 1927 1928class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract( 1929 BaseModel 1930): 1931 input_schema: dict[str, Any] | None = Field( 1932 default=None, 1933 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 1934 ) 1935 participants: ( 1936 list[ 1937 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem 1938 ] 1939 | None 1940 ) = Field( 1941 default=None, 1942 description="Named participant slots declared by the workflow, sorted by name. `null` when the workflow declares none. Values supplied under the top-level `participants` field are agent IDs.", 1943 ) 1944 prefills: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 1945 ..., 1946 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 1947 ) 1948 1949 1950class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails( 1951 BaseModel 1952): 1953 automation_type: str | None = Field( 1954 default=None, 1955 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 1956 ) 1957 invoke_contract: ( 1958 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract 1959 | None 1960 ) = Field( 1961 default=None, 1962 description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. `null` for non-invoked automation types.", 1963 ) 1964 type: Literal["automation"] = Field( 1965 default="automation", 1966 description="Template-details discriminator. Always `automation` for this variant.", 1967 ) 1968 1969 1970class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem( 1971 BaseModel 1972): 1973 description: str | None = Field( 1974 default=None, 1975 description="Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.", 1976 ) 1977 details: ( 1978 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails 1979 | None 1980 ) = Field( 1981 default=None, 1982 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 1983 ) 1984 display_name: str | None = Field( 1985 default=None, 1986 description="Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.", 1987 ) 1988 id: str | None = Field( 1989 default=None, 1990 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 1991 ) 1992 kind: str = Field( 1993 ..., 1994 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 1995 ) 1996 lookup_key: str | None = Field( 1997 default=None, 1998 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 1999 ) 2000 name: str | None = Field( 2001 default=None, 2002 description="Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.", 2003 ) 2004 readme_url: str | None = Field( 2005 default=None, 2006 description="Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2007 ) 2008 virtual_path: str | None = Field( 2009 default=None, 2010 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2011 ) 2012 2013 2014class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(BaseModel): 2015 category_keys: list[str] | None = Field( 2016 default=None, 2017 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2018 ) 2019 created_at: str | None = Field( 2020 default=None, description="When the Solution config was first imported (ISO 8601)." 2021 ) 2022 description: str | None = Field( 2023 default=None, 2024 description="Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.", 2025 ) 2026 events: dict[str, Any] | None = Field( 2027 default=None, 2028 description="Custom analytics events declared in the Solution body's `events:` manifest a map of event key (snake_case) to its definition (`label`, optional `description`, optional typed `fields`). Dashboards use the `label` as the event's display name. Present as an empty object when the body declares none.", 2029 ) 2030 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2031 image_url: str | None = Field( 2032 default=None, 2033 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2034 ) 2035 installed_config_ids: list[str] = Field( 2036 ..., 2037 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2038 ) 2039 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2040 latest_solution: str | None = Field( 2041 default=None, 2042 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2043 ) 2044 latest_version: str | None = Field( 2045 default=None, 2046 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2047 ) 2048 lookup_key: str | None = Field( 2049 default=None, 2050 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2051 ) 2052 metadata: dict[str, Any] | None = Field( 2053 default=None, 2054 description="Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.", 2055 ) 2056 name: str | None = Field( 2057 default=None, 2058 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2059 ) 2060 org: str | None = Field( 2061 default=None, 2062 description="Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.", 2063 ) 2064 org_logo: ( 2065 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo 2066 | None 2067 ) = Field( 2068 default=None, 2069 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. The `url` is a stable, non-expiring capability URL (`refresh_url` is `null` there is nothing to refresh). `null` when `org_slug` is `null` or the org has no logo.", 2070 ) 2071 org_name: str | None = Field( 2072 default=None, 2073 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2074 ) 2075 org_slug: str | None = Field( 2076 default=None, 2077 description="Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.", 2078 ) 2079 owners: list[str] = Field( 2080 ..., 2081 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2082 ) 2083 readme_url: str | None = Field( 2084 default=None, 2085 description="Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2086 ) 2087 screenshot_urls: list[str] | None = Field( 2088 default=None, 2089 description="Absolute URLs of the Solution's gallery screenshots the bundled assets the body's `screenshots:` field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as `image_url` (one shared token, a `v` cache key, and a `file` param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.", 2090 ) 2091 solution_id: str | None = Field( 2092 default=None, 2093 description="Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.", 2094 ) 2095 solution_version: str | None = Field( 2096 default=None, 2097 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2098 ) 2099 tag_keys: list[str] | None = Field( 2100 default=None, 2101 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2102 ) 2103 template_kind: str | None = Field( 2104 default=None, 2105 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2106 ) 2107 templates: list[ 2108 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem 2109 ] = Field( 2110 ..., 2111 description="Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.", 2112 ) 2113 updated_at: str | None = Field( 2114 default=None, description="When the Solution config was last modified (ISO 8601)." 2115 ) 2116 upgrade_available: bool = Field( 2117 ..., 2118 description="`true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.", 2119 ) 2120 virtual_path: str | None = Field( 2121 default=None, 2122 description="The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.", 2123 ) 2124 2125 2126class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(BaseModel): 2127 file: str | None = Field( 2128 default=None, 2129 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2130 ) 2131 height: int | None = Field( 2132 default=None, description="Height of the image in pixels. `null` if not known." 2133 ) 2134 media: str | None = Field( 2135 default=None, 2136 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2137 ) 2138 mime_type: str | None = Field( 2139 default=None, 2140 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2141 ) 2142 refresh_url: str | None = Field( 2143 default=None, 2144 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.", 2145 ) 2146 url: str | None = Field( 2147 default=None, 2148 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.", 2149 ) 2150 width: int | None = Field( 2151 default=None, description="Width of the image in pixels. `null` if not known." 2152 ) 2153 2154 2155class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 2156 BaseModel 2157): 2158 description: str | None = Field( 2159 default=None, 2160 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 2161 ) 2162 name: str = Field( 2163 ..., 2164 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 2165 ) 2166 required: bool = Field( 2167 ..., 2168 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2169 ) 2170 type: str = Field( 2171 ..., 2172 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2173 ) 2174 2175 2176class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills( 2177 BaseModel 2178): 2179 participants: dict[str, Any] | None = Field( 2180 default=None, 2181 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2182 ) 2183 payload: dict[str, Any] | None = Field( 2184 default=None, 2185 description="Partial invocation payload applied by the platform. A caller may omit these values, but supplying a different value at any locked path is rejected.", 2186 ) 2187 2188 2189class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract( 2190 BaseModel 2191): 2192 input_schema: dict[str, Any] | None = Field( 2193 default=None, 2194 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2195 ) 2196 participants: ( 2197 list[ 2198 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2199 ] 2200 | None 2201 ) = Field( 2202 default=None, 2203 description="Named participant slots declared by the workflow, sorted by name. `null` when the workflow declares none. Values supplied under the top-level `participants` field are agent IDs.", 2204 ) 2205 prefills: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2206 ..., 2207 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2208 ) 2209 2210 2211class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails( 2212 BaseModel 2213): 2214 automation_type: str | None = Field( 2215 default=None, 2216 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2217 ) 2218 invoke_contract: ( 2219 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract 2220 | None 2221 ) = Field( 2222 default=None, 2223 description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. `null` for non-invoked automation types.", 2224 ) 2225 type: Literal["automation"] = Field( 2226 default="automation", 2227 description="Template-details discriminator. Always `automation` for this variant.", 2228 ) 2229 2230 2231class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem( 2232 BaseModel 2233): 2234 description: str | None = Field( 2235 default=None, 2236 description="Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.", 2237 ) 2238 details: ( 2239 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails 2240 | None 2241 ) = Field( 2242 default=None, 2243 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2244 ) 2245 display_name: str | None = Field( 2246 default=None, 2247 description="Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.", 2248 ) 2249 id: str | None = Field( 2250 default=None, 2251 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2252 ) 2253 kind: str = Field( 2254 ..., 2255 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2256 ) 2257 lookup_key: str | None = Field( 2258 default=None, 2259 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2260 ) 2261 name: str | None = Field( 2262 default=None, 2263 description="Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.", 2264 ) 2265 readme_url: str | None = Field( 2266 default=None, 2267 description="Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2268 ) 2269 virtual_path: str | None = Field( 2270 default=None, 2271 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2272 ) 2273 2274 2275class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(BaseModel): 2276 category_keys: list[str] | None = Field( 2277 default=None, 2278 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2279 ) 2280 created_at: str | None = Field( 2281 default=None, description="When the Solution config was first imported (ISO 8601)." 2282 ) 2283 description: str | None = Field( 2284 default=None, 2285 description="Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.", 2286 ) 2287 events: dict[str, Any] | None = Field( 2288 default=None, 2289 description="Custom analytics events declared in the Solution body's `events:` manifest a map of event key (snake_case) to its definition (`label`, optional `description`, optional typed `fields`). Dashboards use the `label` as the event's display name. Present as an empty object when the body declares none.", 2290 ) 2291 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2292 image_url: str | None = Field( 2293 default=None, 2294 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2295 ) 2296 installed_config_ids: list[str] = Field( 2297 ..., 2298 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2299 ) 2300 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2301 latest_solution: str | None = Field( 2302 default=None, 2303 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2304 ) 2305 latest_version: str | None = Field( 2306 default=None, 2307 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2308 ) 2309 lookup_key: str | None = Field( 2310 default=None, 2311 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2312 ) 2313 metadata: dict[str, Any] | None = Field( 2314 default=None, 2315 description="Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.", 2316 ) 2317 name: str | None = Field( 2318 default=None, 2319 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2320 ) 2321 org: str | None = Field( 2322 default=None, 2323 description="Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.", 2324 ) 2325 org_logo: ( 2326 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | None 2327 ) = Field( 2328 default=None, 2329 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. The `url` is a stable, non-expiring capability URL (`refresh_url` is `null` there is nothing to refresh). `null` when `org_slug` is `null` or the org has no logo.", 2330 ) 2331 org_name: str | None = Field( 2332 default=None, 2333 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2334 ) 2335 org_slug: str | None = Field( 2336 default=None, 2337 description="Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.", 2338 ) 2339 owners: list[str] = Field( 2340 ..., 2341 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2342 ) 2343 readme_url: str | None = Field( 2344 default=None, 2345 description="Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2346 ) 2347 screenshot_urls: list[str] | None = Field( 2348 default=None, 2349 description="Absolute URLs of the Solution's gallery screenshots the bundled assets the body's `screenshots:` field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as `image_url` (one shared token, a `v` cache key, and a `file` param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.", 2350 ) 2351 solution_id: str | None = Field( 2352 default=None, 2353 description="Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.", 2354 ) 2355 solution_version: str | None = Field( 2356 default=None, 2357 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2358 ) 2359 tag_keys: list[str] | None = Field( 2360 default=None, 2361 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2362 ) 2363 template_kind: str | None = Field( 2364 default=None, 2365 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2366 ) 2367 templates: list[ 2368 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem 2369 ] = Field( 2370 ..., 2371 description="Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.", 2372 ) 2373 updated_at: str | None = Field( 2374 default=None, description="When the Solution config was last modified (ISO 8601)." 2375 ) 2376 upgrade_available: bool = Field( 2377 ..., 2378 description="`true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.", 2379 ) 2380 virtual_path: str | None = Field( 2381 default=None, 2382 description="The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.", 2383 ) 2384 2385 2386class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(BaseModel): 2387 created_at: datetime | None = Field( 2388 default=None, description="When this template config was created (ISO 8601)." 2389 ) 2390 description: str | None = Field( 2391 default=None, 2392 description="Description of the template from the config body. `null` if the current version has no `description` field.", 2393 ) 2394 display_name: str | None = Field( 2395 default=None, 2396 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 2397 ) 2398 id: str = Field(..., description="Template config ID (`cfg_...`).") 2399 kind: str = Field( 2400 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 2401 ) 2402 lookup_key: str | None = Field( 2403 default=None, 2404 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 2405 ) 2406 name: str | None = Field( 2407 default=None, 2408 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 2409 ) 2410 updated_at: datetime | None = Field( 2411 default=None, description="When this template config was last modified (ISO 8601)." 2412 ) 2413 virtual_path: str | None = Field( 2414 default=None, 2415 description="Virtual filesystem path for this template config. `null` if not set.", 2416 ) 2417 2418 2419class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolution(BaseModel): 2420 current_solution: ( 2421 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | None 2422 ) = Field( 2423 default=None, 2424 description="Summary of the current parent Solution config row. `solution` is the pinned Solution version the agent points at; `current_solution` is the source Solution config row as it exists now.", 2425 ) 2426 solution: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution = Field( 2427 ..., 2428 description="Summary of the parent Solution, including `upgrade_available`, `latest_version`, and `latest_solution` when a newer system-scoped version is available for the agent's org-scoped Solution.", 2429 ) 2430 template: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate = Field( 2431 ..., 2432 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2433 ) 2434 2435 2436class OrgThreadListResponseDataItemParticipatingAgentsItem(BaseModel): 2437 acl: OrgThreadListResponseDataItemParticipatingAgentsItemAcl | None = Field( 2438 default=None, 2439 description="Access control list for the agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the agent is accessible to all members of its scope.", 2440 ) 2441 app: str | None = Field( 2442 default=None, description="ID of the application that owns this agent (`dap_...`)." 2443 ) 2444 created_at: str | None = Field( 2445 default=None, description="When the agent was created (ISO 8601)." 2446 ) 2447 default_model: str | None = Field( 2448 default=None, 2449 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2450 ) 2451 description: str | None = Field( 2452 default=None, 2453 description="Human-readable description of what the agent does. `null` if not set.", 2454 ) 2455 email: str | None = Field( 2456 default=None, 2457 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2458 ) 2459 id: str = Field(..., description="Agent ID (`agi_...`).") 2460 identity: str | None = Field( 2461 default=None, 2462 description="System-level identity prompt that shapes the agent's persona and behavior.", 2463 ) 2464 last_applied_template_config: str | None = Field( 2465 default=None, 2466 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2467 ) 2468 lookup_key: str | None = Field( 2469 default=None, 2470 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2471 ) 2472 metadata: dict[str, Any] | None = Field( 2473 default=None, 2474 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2475 ) 2476 name: str | None = Field( 2477 default=None, description="Human-readable display name for the agent. `null` if not set." 2478 ) 2479 org: str | None = Field( 2480 default=None, 2481 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2482 ) 2483 org_name: str | None = Field( 2484 default=None, 2485 description="Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded.", 2486 ) 2487 originator: str | None = Field( 2488 default=None, 2489 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2490 ) 2491 phone_number: str | None = Field( 2492 default=None, 2493 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2494 ) 2495 sandbox: str | None = Field( 2496 default=None, 2497 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2498 ) 2499 source_solution: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolution | None = ( 2500 Field( 2501 default=None, 2502 description="Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes `upgrade_available`, `latest_version`, and `latest_solution` so you can render an upgrade badge without a separate dry-run call. `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints.", 2503 ) 2504 ) 2505 team: str | None = Field( 2506 default=None, 2507 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2508 ) 2509 template_upgrade_available: bool | None = Field( 2510 default=None, 2511 description="True when the agent's last-applied template version is behind the current version of its AgentTemplate config i.e. reapplying the template (a per-agent upgrade) would bring it newer Solution content. Self-clears once the agent is reapplied. Computed on both the list endpoints and single-agent GET. Distinct from `source_solution.upgrade_available`, which compares Solution *versions*: an agent can lag its template (`template_upgrade_available: true`) while the org already holds the latest Solution version (`upgrade_available: false`).", 2512 ) 2513 updated_at: str | None = Field( 2514 default=None, description="When the agent was last modified (ISO 8601)." 2515 ) 2516 user: str | None = Field( 2517 default=None, 2518 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 2519 ) 2520 2521 2522class OrgThreadListResponseDataItemSettings(BaseModel): 2523 agent_enabled: bool | None = Field( 2524 default=None, 2525 description="Whether the AI agent is active for this thread. `true` enables AI responses; `false` disables them. Defaults to `true` when settings have not been explicitly configured. `null` when a client explicitly cleared the setting.", 2526 ) 2527 2528 2529class OrgThreadListResponseDataItem(BaseModel): 2530 agent_user: str | None = Field( 2531 default=None, 2532 description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", 2533 ) 2534 created_at: str | None = Field( 2535 default=None, description="When the thread was created (ISO 8601)." 2536 ) 2537 creator: str | dict[str, Any] | None = Field( 2538 default=None, 2539 description="User who created this thread. Returns a user ID (`usr_...`) by default, or an expanded user object when the association is loaded. `null` if the creator is unknown.", 2540 ) 2541 description: str | None = Field( 2542 default=None, 2543 description="Optional description or purpose statement for the thread. `null` if not set.", 2544 ) 2545 id: str = Field(..., description="Thread ID (`thr_...`).") 2546 is_channel: bool | None = Field( 2547 default=None, 2548 description="Whether this thread operates as a channel a multi-member broadcast-style conversation.", 2549 ) 2550 is_default: bool | None = Field( 2551 default=None, 2552 description="Whether this is the default thread for its owner. Each user or team has at most one default thread.", 2553 ) 2554 is_transient: bool | None = Field( 2555 default=None, 2556 description="Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.", 2557 ) 2558 is_unlisted: bool | None = Field( 2559 default=None, 2560 description="Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.", 2561 ) 2562 key: str | None = Field( 2563 default=None, 2564 description="Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", 2565 ) 2566 kind: str | None = Field( 2567 default=None, 2568 description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"feed"` for a post feed with inline replies, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` and `feed` are explicit creation options; mirror kinds are server-derived.', 2569 ) 2570 last_activity: str | None = Field( 2571 default=None, 2572 description="When the most recent message was posted in this thread, falling back to the thread's creation time if it has no messages. Always populated on thread list endpoints (which order by it, after default threads); `null` on endpoints that don't compute activity enrichment.", 2573 ) 2574 last_message_preview: str | None = Field( 2575 default=None, 2576 description="Single-line snippet of the most recent message's text content (first non-empty line, truncated to 140 characters). Populated on thread list endpoints alongside `last_activity`; `null` when the thread has no messages, the latest message has no text content (e.g. attachment-only), or the endpoint doesn't compute activity enrichment.", 2577 ) 2578 last_message_sender: str | None = Field( 2579 default=None, 2580 description="Display name of the sender of the most recent message the same message `last_message_preview` snippets. Populated on thread list endpoints; `null` when the thread has no messages or the endpoint doesn't compute activity enrichment.", 2581 ) 2582 metadata: dict[str, Any] | None = Field( 2583 default=None, 2584 description="Arbitrary key-value metadata attached to the thread. Shape is application-defined; `null` if no metadata has been set.", 2585 ) 2586 muted: bool | None = Field( 2587 default=None, 2588 description="Whether the authenticated user has muted notifications for this thread. `true` suppresses all notification delivery.", 2589 ) 2590 org: str | None = Field( 2591 default=None, 2592 description="ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", 2593 ) 2594 parent_message: OrgThreadListResponseDataItemParentMessage | None = Field( 2595 default=None, 2596 description="The message that spawned this thread as a sub-thread. `null` for top-level threads.", 2597 ) 2598 participant: list[str] | None = Field( 2599 default=None, 2600 description="Array of participant user IDs (`usr_...`) who are members of this thread.", 2601 ) 2602 participants: list[OrgThreadListResponseDataItemParticipantsItem] | None = Field( 2603 default=None, 2604 description="Expanded participant user objects for each member of this thread. Populated only when the association is loaded.", 2605 ) 2606 participating_actor: list[str] | None = Field( 2607 default=None, 2608 description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", 2609 ) 2610 participating_agents: list[OrgThreadListResponseDataItemParticipatingAgentsItem] | None = Field( 2611 default=None, 2612 description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", 2613 ) 2614 role: str | None = Field( 2615 default=None, 2616 description='The authenticated user\'s membership role in this thread, e.g. `"owner"`, `"member"`, or `"viewer"`. `null` if the user is not a member.', 2617 ) 2618 sandbox: str | None = Field( 2619 default=None, 2620 description="ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", 2621 ) 2622 settings: OrgThreadListResponseDataItemSettings | None = Field( 2623 default=None, 2624 description="Per-thread configuration settings controlling AI agent behavior for this thread.", 2625 ) 2626 slug: str | None = Field( 2627 default=None, 2628 description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", 2629 ) 2630 sub_threads: list[dict[str, Any]] | None = Field( 2631 default=None, 2632 description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", 2633 ) 2634 tags: list[str] | None = Field( 2635 default=None, 2636 description='Status tags on the thread (e.g. `"blocked"`, `"needs-review"`). Edited by any thread participant via the `/threads/:thread/tags` endpoints and filterable on the thread list endpoints. Empty array if none set.', 2637 ) 2638 team: str | None = Field( 2639 default=None, 2640 description="ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", 2641 ) 2642 title: str | None = Field( 2643 default=None, 2644 description="Human-readable name of the thread. `null` if no title has been set.", 2645 ) 2646 ttl: str | None = Field( 2647 default=None, 2648 description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", 2649 ) 2650 unread_count: int | None = Field( 2651 default=None, 2652 description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", 2653 ) 2654 updated_at: str | None = Field( 2655 default=None, description="When the thread was last modified (ISO 8601)." 2656 ) 2657 user: str | None = Field( 2658 default=None, 2659 description="ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", 2660 ) 2661 visibility: Literal["team", "restricted", "private", "org"] = Field( 2662 ..., 2663 description="Who can read the thread: `team` for every owning-team member, `restricted` for team-readable threads with an explicit roster, `private` for roster-only access, or `org` for every member of the owning organization.", 2664 ) 2665 2666 2667class OrgThreadListResponse(BaseModel): 2668 """ 2669 Successful response 2670 """ 2671 2672 data: list[OrgThreadListResponseDataItem] = Field( 2673 ..., description="Array of org-visibility thread objects." 2674 ) 2675 2676 2677class OrgListResponseDataItem(BaseModel): 2678 domain: str | None = Field( 2679 default=None, 2680 description="Company domain. For personal orgs, the owner email is returned only to a viewer in that org.", 2681 ) 2682 id: str = Field(..., description="Organization ID (`org_...`).") 2683 kind: Literal["company", "personal"] = Field( 2684 ..., description="Whether this is a company-domain org or a person-owned personal org." 2685 ) 2686 name: str = Field(..., description="Display name of the organization.") 2687 2688 2689class OrgListResponse(BaseModel): 2690 """ 2691 Successful response 2692 """ 2693 2694 data: list[OrgListResponseDataItem] = Field( 2695 ..., description="Array of organization objects for the current page." 2696 ) 2697 has_next: bool | None = Field( 2698 default=None, description="`true` when a subsequent page exists; `false` on the last page." 2699 ) 2700 has_prev: bool | None = Field( 2701 default=None, description="`true` when a previous page exists; `false` on the first page." 2702 ) 2703 page: int | None = Field(default=None, description="The current page number returned.") 2704 page_size: int | None = Field( 2705 default=None, description="The number of results per page used for this response." 2706 ) 2707 total_entries: int | None = Field( 2708 default=None, 2709 description="Total number of organizations matching the query across all pages.", 2710 ) 2711 total_pages: int | None = Field( 2712 default=None, description="Total number of pages for the current query and page size." 2713 ) 2714 2715 2716class OrgArtifactsResponseDataItemAclAddItem(BaseModel): 2717 actions: list[str] = Field( 2718 ..., 2719 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2720 ) 2721 principal: str | None = Field( 2722 default=None, 2723 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 2724 ) 2725 principal_type: str = Field( 2726 ..., 2727 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2728 ) 2729 2730 2731class OrgArtifactsResponseDataItemAclGrantsItem(BaseModel): 2732 actions: list[str] = Field( 2733 ..., 2734 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2735 ) 2736 principal: str | None = Field( 2737 default=None, 2738 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 2739 ) 2740 principal_type: str = Field( 2741 ..., 2742 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2743 ) 2744 2745 2746class OrgArtifactsResponseDataItemAclRemoveItem(BaseModel): 2747 principal: str | None = Field( 2748 default=None, 2749 description='The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.', 2750 ) 2751 principal_type: str = Field( 2752 ..., 2753 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2754 ) 2755 2756 2757class OrgArtifactsResponseDataItemAcl(BaseModel): 2758 add: list[OrgArtifactsResponseDataItemAclAddItem] | None = Field( 2759 default=None, 2760 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 2761 ) 2762 grants: list[OrgArtifactsResponseDataItemAclGrantsItem] | None = Field( 2763 default=None, 2764 description="Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", 2765 ) 2766 remove: list[OrgArtifactsResponseDataItemAclRemoveItem] | None = Field( 2767 default=None, 2768 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 2769 ) 2770 2771 2772class OrgArtifactsResponseDataItemImageSource(BaseModel): 2773 file: str | None = Field( 2774 default=None, 2775 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2776 ) 2777 height: int | None = Field( 2778 default=None, description="Height of the image in pixels. `null` if not known." 2779 ) 2780 media: str | None = Field( 2781 default=None, 2782 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2783 ) 2784 mime_type: str | None = Field( 2785 default=None, 2786 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2787 ) 2788 refresh_url: str | None = Field( 2789 default=None, 2790 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.", 2791 ) 2792 url: str | None = Field( 2793 default=None, 2794 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.", 2795 ) 2796 width: int | None = Field( 2797 default=None, description="Width of the image in pixels. `null` if not known." 2798 ) 2799 2800 2801class OrgArtifactsResponseDataItem(BaseModel): 2802 acl: OrgArtifactsResponseDataItemAcl | None = Field( 2803 default=None, 2804 description="Access control list for the artifact. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions` (`read`, `write`). `null` when the artifact has no grants or the viewer is not its owner.", 2805 ) 2806 agent: str | None = Field( 2807 default=None, 2808 description="ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.", 2809 ) 2810 content_type: str | None = Field( 2811 default=None, 2812 description='MIME type of the current version\'s file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.', 2813 ) 2814 created_at: datetime | None = Field( 2815 default=None, description="When the artifact was first created (ISO 8601)." 2816 ) 2817 current_version: str | None = Field( 2818 default=None, 2819 description="ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.", 2820 ) 2821 description: str | None = Field( 2822 default=None, 2823 description="Optional longer description of the artifact's contents or purpose. `null` if not set.", 2824 ) 2825 file: str | None = Field( 2826 default=None, 2827 description="Storage file ID for the current version (`fil_...`). `null` if no file is attached.", 2828 ) 2829 file_name: str | None = Field( 2830 default=None, 2831 description='Original filename of the current version\'s file, e.g. `"output.csv"`. `null` if no file is attached.', 2832 ) 2833 file_url: str | None = Field( 2834 default=None, 2835 description="Short-lived signed URL for downloading the current version's file. `null` if no file is attached.", 2836 ) 2837 group_key: str | None = Field( 2838 default=None, 2839 description="Optional nonunique, case-sensitive grouping key, limited to 1024 UTF-8 bytes. Null when unset; belongs to the artifact, not a content version.", 2840 ) 2841 id: str = Field(..., description="Artifact ID (`art_...`).") 2842 image_source: OrgArtifactsResponseDataItemImageSource | None = Field( 2843 default=None, 2844 description='Image source metadata for rendering the current version\'s file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.', 2845 ) 2846 name: str | None = Field( 2847 default=None, 2848 description='Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.', 2849 ) 2850 org: str | None = Field( 2851 default=None, description="ID of the organization this artifact belongs to (`org_...`)." 2852 ) 2853 sandbox: str | None = Field( 2854 default=None, 2855 description="Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.", 2856 ) 2857 system: bool | None = Field( 2858 default=None, 2859 description="True when the artifact has no user, team, or agent owner. An organization may own a system artifact.", 2860 ) 2861 team: str | None = Field( 2862 default=None, 2863 description="ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.", 2864 ) 2865 thread: str | None = Field( 2866 default=None, 2867 description="ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.", 2868 ) 2869 updated_at: datetime | None = Field( 2870 default=None, description="When the artifact record was last modified (ISO 8601)." 2871 ) 2872 user: str | None = Field( 2873 default=None, 2874 description="ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.", 2875 ) 2876 version: int | None = Field( 2877 default=None, 2878 description="Current version number of the artifact. Increments each time a new version is published.", 2879 ) 2880 2881 2882class OrgArtifactsResponse(BaseModel): 2883 """ 2884 Successful response 2885 """ 2886 2887 after_cursor: str | None = None 2888 before_cursor: str | None = Field( 2889 default=None, description="Always null; pagination is forward-only." 2890 ) 2891 data: list[OrgArtifactsResponseDataItem] 2892 has_more: bool 2893 2894 2895class OrgLinkedAccountsResponseDataItem(BaseModel): 2896 account_id: str = Field( 2897 ..., description="The service's name for the account: the login, for GitHub." 2898 ) 2899 provider: str = Field( 2900 ..., description='Service the account is on. Currently always `"github"`.' 2901 ) 2902 user: str = Field(..., description="User ID (`usr_...`) the account belongs to.") 2903 2904 2905class OrgLinkedAccountsResponse(BaseModel): 2906 """ 2907 Successful response 2908 """ 2909 2910 after_cursor: str | None = None 2911 before_cursor: str | None = Field( 2912 default=None, description="Always null; pagination is forward-only." 2913 ) 2914 data: list[OrgLinkedAccountsResponseDataItem] = Field( 2915 ..., description="Linked accounts, by user." 2916 ) 2917 has_more: bool 2918 2919 2920class OrgTaskEpicsResponseDataItemNextReadyItem(BaseModel): 2921 id: str 2922 name: str 2923 priority: int 2924 status: str 2925 2926 2927class OrgTaskEpicsResponseDataItemRootBlockersItem(BaseModel): 2928 downstream_count: int 2929 id: str 2930 name: str 2931 priority: int 2932 status: str 2933 2934 2935class OrgTaskEpicsResponseDataItem(BaseModel): 2936 blocked_count: int 2937 counts: dict[str, Any] = Field( 2938 ..., description="Task counts keyed by status, including closed tasks." 2939 ) 2940 epic: str 2941 next_ready: list[OrgTaskEpicsResponseDataItemNextReadyItem] 2942 root_blockers: list[OrgTaskEpicsResponseDataItemRootBlockersItem] 2943 root_blockers_partial: bool = Field( 2944 ..., description="True when root ranking used a truncated in-epic graph." 2945 ) 2946 top_open_priority: int | None = None 2947 updated_at: datetime 2948 2949 2950class OrgTaskEpicsResponse(BaseModel): 2951 """ 2952 Successful response 2953 """ 2954 2955 after_cursor: str | None = None 2956 before_cursor: str | None = None 2957 data: list[OrgTaskEpicsResponseDataItem] 2958 has_more: bool 2959 no_epic_open_count: int 2960 2961 2962class AsyncOrgTaskResource: 2963 def __init__(self, http: HttpClient): 2964 self._http = http 2965 2966 async def list( 2967 self, 2968 org: str, 2969 *, 2970 status: str | None = None, 2971 owner_user: str | None = None, 2972 owner_agent: str | None = None, 2973 priority: int | None = None, 2974 tag: str | None = None, 2975 parent: str | None = None, 2976 source_scope: str | None = None, 2977 source_type: str | None = None, 2978 source_id: str | None = None, 2979 epic: str | None = None, 2980 search: str | None = None, 2981 sort: str | None = None, 2982 order: str | None = None, 2983 due_before: str | None = None, 2984 due_after: str | None = None, 2985 overdue: bool | None = None, 2986 ready: bool | None = None, 2987 attention: bool | None = None, 2988 limit: int | None = None, 2989 after_cursor: str | None = None, 2990 ) -> OrgTaskListResponse: 2991 """ 2992 List an organization's tasks 2993 Returns org-owned tasks for the specified organization: rows with the org 2994 tenant and no narrower user/team/agent scope. Explicitly personal, team, or 2995 agent tasks are excluded here; list those via the user/team collections or 2996 fetch them directly when authorized. 2997 Every organization member may list. App-scoped developer and 2998 server-to-server callers supply the org in the route. 2999 3000 Args: 3001 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3002 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3003 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3004 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3005 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3006 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3007 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3008 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3009 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3010 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3011 epic: Return only tasks with this exact epic label. 3012 search: Restrict results to tasks whose name or description contains this string. 3013 sort: Sort key. One of `"created"` (default most recently created first), `"due_date"` (soonest due first; tasks without a due date always sort last), or `"priority"` (most urgent first). Ties break by most recently created. 3014 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3015 due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. 3016 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3017 overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. 3018 ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. 3019 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3020 limit: Maximum number of tasks to return. Capped at 100. 3021 after_cursor: Opaque cursor returned by the previous page. 3022 3023 Returns: 3024 Successful response 3025 """ 3026 query: dict[str, object] = {} 3027 if status is not None: 3028 query["status"] = status 3029 if owner_user is not None: 3030 query["owner_user"] = owner_user 3031 if owner_agent is not None: 3032 query["owner_agent"] = owner_agent 3033 if priority is not None: 3034 query["priority"] = priority 3035 if tag is not None: 3036 query["tag"] = tag 3037 if parent is not None: 3038 query["parent"] = parent 3039 if source_scope is not None: 3040 query["source_scope"] = source_scope 3041 if source_type is not None: 3042 query["source_type"] = source_type 3043 if source_id is not None: 3044 query["source_id"] = source_id 3045 if epic is not None: 3046 query["epic"] = epic 3047 if search is not None: 3048 query["search"] = search 3049 if sort is not None: 3050 query["sort"] = sort 3051 if order is not None: 3052 query["order"] = order 3053 if due_before is not None: 3054 query["due_before"] = due_before 3055 if due_after is not None: 3056 query["due_after"] = due_after 3057 if overdue is not None: 3058 query["overdue"] = overdue 3059 if ready is not None: 3060 query["ready"] = ready 3061 if attention is not None: 3062 query["attention"] = attention 3063 if limit is not None: 3064 query["limit"] = limit 3065 if after_cursor is not None: 3066 query["after_cursor"] = after_cursor 3067 return await self._http.request( 3068 f"/api/v1/orgs/{org}/tasks", 3069 query=query, 3070 response_type=OrgTaskListResponse, 3071 ) 3072 3073 async def create(self, org: str, input: OrgTaskCreateInput) -> Task: 3074 """ 3075 Create a task for an organization 3076 Creates a new org-owned task (org tenant, no narrower user/team/agent 3077 scope) and returns the full task object. User-authenticated calls are 3078 attributed to the authenticated user or agent. App-scoped developer and 3079 server-to-server callers must provide an explicit `user` or `agent` actor 3080 for the organization. Every referenced principal is validated against the 3081 app and organization before creation. 3082 3083 Args: 3084 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3085 input: Request body. 3086 input.agent: Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization. 3087 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3088 input.user: Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`. 3089 3090 Returns: 3091 The newly created task. 3092 """ 3093 return await self._http.request( 3094 f"/api/v1/orgs/{org}/tasks", 3095 method="POST", 3096 body=input, 3097 response_type=Task, 3098 ) 3099 3100 async def blocker_cycles( 3101 self, org: str, *, limit: int | None = None, after_cursor: str | None = None 3102 ) -> OrgTaskBlockerCyclesResponse: 3103 """ 3104 List task blocker cycles for an organization 3105 Runs an on-demand diagnostic over unfinished org-owned tasks for the 3106 specified organization and returns a forward cursor-paginated page of 3107 complete cyclic blocker components. Detection is bounded to owners with at 3108 most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent 3109 task updates, lease acquisition, or completion. 3110 3111 Args: 3112 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3113 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3114 after_cursor: Opaque cursor returned by the preceding page. 3115 3116 Returns: 3117 Successful response 3118 """ 3119 query: dict[str, object] = {} 3120 if limit is not None: 3121 query["limit"] = limit 3122 if after_cursor is not None: 3123 query["after_cursor"] = after_cursor 3124 return await self._http.request( 3125 f"/api/v1/orgs/{org}/tasks/blocker_cycles", 3126 query=query, 3127 response_type=OrgTaskBlockerCyclesResponse, 3128 ) 3129 3130 async def by_source(self, org: str, input: OrgTaskBySourceInput) -> TaskEnsureResult: 3131 """ 3132 Find or create a task by source 3133 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3134 3135 Args: 3136 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3137 input: Request body. 3138 input.agent: Explicit acting agent for privileged callers. 3139 input.description: Initial task description. 3140 input.epic: Initial epic grouping. 3141 input.name: Initial task name. 3142 input.source_id: Source identity, for example owner/repo#123. 3143 input.source_scope: Source scope, for example github. 3144 input.source_type: Source type, for example pull_request. 3145 input.status: Initial task status. 3146 input.team: Team owner. 3147 input.user: User owner, or explicit acting user on a team route. 3148 3149 Returns: 3150 The task and whether this request created it. 3151 """ 3152 return await self._http.request( 3153 f"/api/v1/orgs/{org}/tasks/by-source", 3154 method="PUT", 3155 body=input, 3156 response_type=TaskEnsureResult, 3157 ) 3158 3159 async def metrics(self, org: str, *, days: int | None = None) -> OrgTaskMetricsResponse: 3160 """ 3161 Get task activity metrics for an organization 3162 Returns task activity metrics scoped to org-owned tasks (org tenant, no 3163 narrower user/team/agent scope). `open` counts currently open or 3164 in-progress org tasks, `created` counts tasks inserted in the UTC-day 3165 window, and `completed` counts tasks whose `closed_at` falls in that window 3166 while still in a closed status. Hard-deleted tasks are absent from the 3167 projection and therefore omitted. The daily series is zero-filled across 3168 the requested window and includes reconstructed end-of-day `open` stock. 3169 Any organization member may read this count-only summary. Requests from 3170 callers without org access return 404 so organization existence is not 3171 disclosed. 3172 3173 Args: 3174 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3175 days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30. 3176 3177 Returns: 3178 Successful response 3179 """ 3180 query: dict[str, object] = {} 3181 if days is not None: 3182 query["days"] = days 3183 return await self._http.request( 3184 f"/api/v1/orgs/{org}/tasks/metrics", 3185 query=query, 3186 response_type=OrgTaskMetricsResponse, 3187 ) 3188 3189 async def ready( 3190 self, 3191 org: str, 3192 *, 3193 explain: bool | None = None, 3194 assigned_to_me: bool | None = None, 3195 source_scope: str | None = None, 3196 source_type: str | None = None, 3197 source_id: str | None = None, 3198 epic: str | None = None, 3199 limit: int | None = None, 3200 after_cursor: str | None = None, 3201 ) -> OrgTaskReadyResponse: 3202 """ 3203 List an organization's ready tasks 3204 Returns open org-owned tasks with no unfinished blockers and no active 3205 session lease. Readiness is calculated by the server from the current task 3206 projection. It is a snapshot, not a reservation; claim a task lease before 3207 starting work. 3208 Results are ordered by priority (0, the most urgent, first), then oldest 3209 first, so the first page is always the most urgent ready work. 3210 Pass `explain=true` to include every open task with a stable readiness reason. 3211 3212 Args: 3213 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3214 explain: Include blocked and actively leased open tasks with exclusion reasons. 3215 assigned_to_me: Only include tasks assigned to the authenticated user. 3216 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3217 source_type: Only include tasks whose source matches this object kind. 3218 source_id: Only include tasks whose source matches this object identity. 3219 epic: Only include tasks with this exact epic label. 3220 limit: Maximum number of readiness entries to return. Capped at 100. 3221 after_cursor: Opaque cursor returned by the previous page. 3222 3223 Returns: 3224 Successful response 3225 """ 3226 query: dict[str, object] = {} 3227 if explain is not None: 3228 query["explain"] = explain 3229 if assigned_to_me is not None: 3230 query["assigned_to_me"] = assigned_to_me 3231 if source_scope is not None: 3232 query["source_scope"] = source_scope 3233 if source_type is not None: 3234 query["source_type"] = source_type 3235 if source_id is not None: 3236 query["source_id"] = source_id 3237 if epic is not None: 3238 query["epic"] = epic 3239 if limit is not None: 3240 query["limit"] = limit 3241 if after_cursor is not None: 3242 query["after_cursor"] = after_cursor 3243 return await self._http.request( 3244 f"/api/v1/orgs/{org}/tasks/ready", 3245 query=query, 3246 response_type=OrgTaskReadyResponse, 3247 ) 3248 3249 async def search( 3250 self, 3251 org: str, 3252 *, 3253 q: str | None = None, 3254 query: str | None = None, 3255 status: str | None = None, 3256 owner_user: str | None = None, 3257 owner_agent: str | None = None, 3258 priority: int | None = None, 3259 tag: str | None = None, 3260 parent: str | None = None, 3261 source_scope: str | None = None, 3262 source_type: str | None = None, 3263 source_id: str | None = None, 3264 epic: str | None = None, 3265 limit: int | None = None, 3266 after_cursor: str | None = None, 3267 ) -> OrgTaskSearchResponse: 3268 """ 3269 Search an organization's tasks 3270 Performs a full-text search over org-owned tasks for the specified 3271 organization and returns matching results. Combine `q` with the optional 3272 filters to narrow the result set further. When no query is provided, the 3273 endpoint behaves like a filtered list. 3274 The `query` field in the response echoes the effective search query. 3275 Explicitly personal, team, or agent tasks are excluded here. 3276 3277 Args: 3278 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3279 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3280 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3281 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3282 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3283 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3284 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3285 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3286 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3287 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3288 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3289 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3290 epic: Return only tasks with this exact epic label. 3291 limit: Maximum number of tasks to return. Capped at 100. 3292 after_cursor: Opaque cursor returned by the previous page. 3293 3294 Returns: 3295 Successful response 3296 """ 3297 query: dict[str, object] = {} 3298 if q is not None: 3299 query["q"] = q 3300 if query is not None: 3301 query["query"] = query 3302 if status is not None: 3303 query["status"] = status 3304 if owner_user is not None: 3305 query["owner_user"] = owner_user 3306 if owner_agent is not None: 3307 query["owner_agent"] = owner_agent 3308 if priority is not None: 3309 query["priority"] = priority 3310 if tag is not None: 3311 query["tag"] = tag 3312 if parent is not None: 3313 query["parent"] = parent 3314 if source_scope is not None: 3315 query["source_scope"] = source_scope 3316 if source_type is not None: 3317 query["source_type"] = source_type 3318 if source_id is not None: 3319 query["source_id"] = source_id 3320 if epic is not None: 3321 query["epic"] = epic 3322 if limit is not None: 3323 query["limit"] = limit 3324 if after_cursor is not None: 3325 query["after_cursor"] = after_cursor 3326 return await self._http.request( 3327 f"/api/v1/orgs/{org}/tasks/search", 3328 query=query, 3329 response_type=OrgTaskSearchResponse, 3330 ) 3331 3332 3333class AsyncOrgThreadResource: 3334 def __init__(self, http: HttpClient): 3335 self._http = http 3336 3337 async def list(self, org: str, *, key: str | None = None) -> OrgThreadListResponse: 3338 """ 3339 List organization-visibility threads 3340 Returns org-visibility threads for the specified organization. Every member 3341 of the organization can list these threads; they require no team membership. 3342 App-scoped developer tokens for the organization's app can list them too. 3343 3344 Args: 3345 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3346 key: Optional exact thread key, for example `support-room`. 3347 3348 Returns: 3349 Successful response 3350 """ 3351 query: dict[str, object] = {} 3352 if key is not None: 3353 query["key"] = key 3354 return await self._http.request( 3355 f"/api/v1/orgs/{org}/threads", 3356 query=query, 3357 response_type=OrgThreadListResponse, 3358 ) 3359 3360 async def create(self, org: str, input: OrgThreadCreateInput) -> Thread: 3361 """ 3362 Create an organization-visibility thread 3363 Creates a thread owned by the organization rather than a team, user, or agent. 3364 Every member of the organization can read and post without joining. The 3365 authenticated caller must be an organization administrator, or use an 3366 app-scoped developer token for the organization's app. 3367 When `thread.key` is supplied, creation is idempotent: a second call with the 3368 same key returns the existing org-visibility thread instead of inserting a 3369 duplicate. 3370 3371 Args: 3372 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3373 input: Request body. 3374 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3375 input.thread: Attributes for the new thread. Visibility is forced to `org`. 3376 3377 Returns: 3378 The organization-visibility thread. 3379 """ 3380 return await self._http.request( 3381 f"/api/v1/orgs/{org}/threads", 3382 method="POST", 3383 body=input, 3384 response_type=Thread, 3385 ) 3386 3387 3388class AsyncOrgResource: 3389 def __init__(self, http: HttpClient): 3390 self._http = http 3391 self.tasks = AsyncOrgTaskResource(http) 3392 self.threads = AsyncOrgThreadResource(http) 3393 3394 async def list( 3395 self, *, search: str | None = None, page: int | None = None, page_size: int | None = None 3396 ) -> OrgListResponse: 3397 """ 3398 Search organizations 3399 Returns a paginated list of organizations within the authenticated app scope, 3400 optionally filtered by a free-text search term matched against name, slug, and 3401 domain (case-insensitive). Results are ordered by relevance when a search term 3402 is provided, and by creation time descending otherwise. 3403 The response includes only public-facing organization fields: ID, name, domain, 3404 and logo. Use the developer-scoped org endpoints to access full organization 3405 records. 3406 Pagination is offset-based. Pass `page` and `page_size` to navigate through 3407 results. The `has_next` and `has_prev` fields indicate whether adjacent pages 3408 exist. 3409 3410 Args: 3411 search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app. 3412 page: Page number to retrieve, starting at `1`. Defaults to `1` when omitted. 3413 page_size: Number of organizations to return per page. Defaults to `25`; maximum is `100`. 3414 3415 Returns: 3416 Successful response 3417 """ 3418 query: dict[str, object] = {} 3419 if search is not None: 3420 query["search"] = search 3421 if page is not None: 3422 query["page"] = page 3423 if page_size is not None: 3424 query["page_size"] = page_size 3425 return await self._http.request("/api/v1/orgs", query=query, response_type=OrgListResponse) 3426 3427 async def artifacts( 3428 self, 3429 org: str, 3430 *, 3431 limit: int | None = None, 3432 after_cursor: str | None = None, 3433 group_key: str | None = None, 3434 group_key_prefix: str | None = None, 3435 ) -> OrgArtifactsResponse: 3436 """ 3437 List completed organization artifacts 3438 Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded. 3439 3440 Args: 3441 org: Organization ID. 3442 limit: Maximum snapshots returned, from 1 to 100. 3443 after_cursor: Opaque cursor for the next page of older snapshots. 3444 group_key: Exact, case-sensitive grouping key. 3445 group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key. 3446 3447 Returns: 3448 Successful response 3449 """ 3450 query: dict[str, object] = {} 3451 if limit is not None: 3452 query["limit"] = limit 3453 if after_cursor is not None: 3454 query["after_cursor"] = after_cursor 3455 if group_key is not None: 3456 query["group_key"] = group_key 3457 if group_key_prefix is not None: 3458 query["group_key_prefix"] = group_key_prefix 3459 return await self._http.request( 3460 f"/api/v1/orgs/{org}/artifacts", 3461 query=query, 3462 response_type=OrgArtifactsResponse, 3463 ) 3464 3465 async def linked_accounts( 3466 self, 3467 org: str, 3468 *, 3469 user: builtins.list[str] | None = None, 3470 limit: int | None = None, 3471 after_cursor: str | None = None, 3472 ) -> OrgLinkedAccountsResponse: 3473 """ 3474 List an organization's linked accounts 3475 Returns the GitHub login each user in the organization signed in with, so 3476 clients can tell that a pull request's author and a Platform user are the 3477 same person. Users who never signed in with GitHub are absent. Any viewer 3478 acting within the organization can list them; other viewers get 404. 3479 Pass `user` to look up specific users instead of listing the whole 3480 organization. Results are ordered by user and paginated forward with 3481 `after_cursor`. 3482 3483 Args: 3484 org: Organization ID (`org_...`) whose linked accounts should be listed. 3485 user: Up to 100 user IDs (`usr_...`) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. 3486 limit: Maximum accounts returned, from 1 to 100. 3487 after_cursor: Opaque cursor for the next page. 3488 3489 Returns: 3490 Successful response 3491 """ 3492 query: dict[str, object] = {} 3493 if user is not None: 3494 query["user"] = user 3495 if limit is not None: 3496 query["limit"] = limit 3497 if after_cursor is not None: 3498 query["after_cursor"] = after_cursor 3499 return await self._http.request( 3500 f"/api/v1/orgs/{org}/linked_accounts", 3501 query=query, 3502 response_type=OrgLinkedAccountsResponse, 3503 ) 3504 3505 async def task_epics( 3506 self, 3507 org: str, 3508 *, 3509 source_scope: str | None = None, 3510 source_type: str | None = None, 3511 source_id: str | None = None, 3512 top_priority: int | None = None, 3513 include_closed: bool | None = None, 3514 limit: int | None = None, 3515 after_cursor: str | None = None, 3516 ) -> OrgTaskEpicsResponse: 3517 """ 3518 List an organization's epic summaries 3519 Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 3520 3521 Args: 3522 org: Organization ID (`org_...`) owning the tasks. 3523 source_scope: Exact source scope; supply all three source fields. 3524 source_type: Exact source type. 3525 source_id: Exact source ID. 3526 top_priority: Exact highest open priority, from 0 to 4. 3527 include_closed: Include epics with no non-closed tasks; defaults to false. 3528 limit: Maximum epics; defaults to 50, capped at 100. 3529 after_cursor: Opaque forward cursor from the preceding page. 3530 3531 Returns: 3532 Successful response 3533 """ 3534 query: dict[str, object] = {} 3535 if source_scope is not None: 3536 query["source_scope"] = source_scope 3537 if source_type is not None: 3538 query["source_type"] = source_type 3539 if source_id is not None: 3540 query["source_id"] = source_id 3541 if top_priority is not None: 3542 query["top_priority"] = top_priority 3543 if include_closed is not None: 3544 query["include_closed"] = include_closed 3545 if limit is not None: 3546 query["limit"] = limit 3547 if after_cursor is not None: 3548 query["after_cursor"] = after_cursor 3549 return await self._http.request( 3550 f"/api/v1/orgs/{org}/task_epics", 3551 query=query, 3552 response_type=OrgTaskEpicsResponse, 3553 ) 3554 3555 3556class OrgTaskResource: 3557 def __init__(self, http: SyncHttpClient): 3558 self._http = http 3559 3560 def list( 3561 self, 3562 org: str, 3563 *, 3564 status: str | None = None, 3565 owner_user: str | None = None, 3566 owner_agent: str | None = None, 3567 priority: int | None = None, 3568 tag: str | None = None, 3569 parent: str | None = None, 3570 source_scope: str | None = None, 3571 source_type: str | None = None, 3572 source_id: str | None = None, 3573 epic: str | None = None, 3574 search: str | None = None, 3575 sort: str | None = None, 3576 order: str | None = None, 3577 due_before: str | None = None, 3578 due_after: str | None = None, 3579 overdue: bool | None = None, 3580 ready: bool | None = None, 3581 attention: bool | None = None, 3582 limit: int | None = None, 3583 after_cursor: str | None = None, 3584 ) -> OrgTaskListResponse: 3585 """ 3586 List an organization's tasks 3587 Returns org-owned tasks for the specified organization: rows with the org 3588 tenant and no narrower user/team/agent scope. Explicitly personal, team, or 3589 agent tasks are excluded here; list those via the user/team collections or 3590 fetch them directly when authorized. 3591 Every organization member may list. App-scoped developer and 3592 server-to-server callers supply the org in the route. 3593 3594 Args: 3595 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3596 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3597 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3598 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3599 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3600 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3601 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3602 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3603 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3604 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3605 epic: Return only tasks with this exact epic label. 3606 search: Restrict results to tasks whose name or description contains this string. 3607 sort: Sort key. One of `"created"` (default most recently created first), `"due_date"` (soonest due first; tasks without a due date always sort last), or `"priority"` (most urgent first). Ties break by most recently created. 3608 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3609 due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. 3610 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3611 overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. 3612 ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. 3613 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3614 limit: Maximum number of tasks to return. Capped at 100. 3615 after_cursor: Opaque cursor returned by the previous page. 3616 3617 Returns: 3618 Successful response 3619 """ 3620 query: dict[str, object] = {} 3621 if status is not None: 3622 query["status"] = status 3623 if owner_user is not None: 3624 query["owner_user"] = owner_user 3625 if owner_agent is not None: 3626 query["owner_agent"] = owner_agent 3627 if priority is not None: 3628 query["priority"] = priority 3629 if tag is not None: 3630 query["tag"] = tag 3631 if parent is not None: 3632 query["parent"] = parent 3633 if source_scope is not None: 3634 query["source_scope"] = source_scope 3635 if source_type is not None: 3636 query["source_type"] = source_type 3637 if source_id is not None: 3638 query["source_id"] = source_id 3639 if epic is not None: 3640 query["epic"] = epic 3641 if search is not None: 3642 query["search"] = search 3643 if sort is not None: 3644 query["sort"] = sort 3645 if order is not None: 3646 query["order"] = order 3647 if due_before is not None: 3648 query["due_before"] = due_before 3649 if due_after is not None: 3650 query["due_after"] = due_after 3651 if overdue is not None: 3652 query["overdue"] = overdue 3653 if ready is not None: 3654 query["ready"] = ready 3655 if attention is not None: 3656 query["attention"] = attention 3657 if limit is not None: 3658 query["limit"] = limit 3659 if after_cursor is not None: 3660 query["after_cursor"] = after_cursor 3661 return self._http.request( 3662 f"/api/v1/orgs/{org}/tasks", 3663 query=query, 3664 response_type=OrgTaskListResponse, 3665 ) 3666 3667 def create(self, org: str, input: OrgTaskCreateInput) -> Task: 3668 """ 3669 Create a task for an organization 3670 Creates a new org-owned task (org tenant, no narrower user/team/agent 3671 scope) and returns the full task object. User-authenticated calls are 3672 attributed to the authenticated user or agent. App-scoped developer and 3673 server-to-server callers must provide an explicit `user` or `agent` actor 3674 for the organization. Every referenced principal is validated against the 3675 app and organization before creation. 3676 3677 Args: 3678 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3679 input: Request body. 3680 input.agent: Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization. 3681 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3682 input.user: Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`. 3683 3684 Returns: 3685 The newly created task. 3686 """ 3687 return self._http.request( 3688 f"/api/v1/orgs/{org}/tasks", 3689 method="POST", 3690 body=input, 3691 response_type=Task, 3692 ) 3693 3694 def blocker_cycles( 3695 self, org: str, *, limit: int | None = None, after_cursor: str | None = None 3696 ) -> OrgTaskBlockerCyclesResponse: 3697 """ 3698 List task blocker cycles for an organization 3699 Runs an on-demand diagnostic over unfinished org-owned tasks for the 3700 specified organization and returns a forward cursor-paginated page of 3701 complete cyclic blocker components. Detection is bounded to owners with at 3702 most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent 3703 task updates, lease acquisition, or completion. 3704 3705 Args: 3706 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3707 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3708 after_cursor: Opaque cursor returned by the preceding page. 3709 3710 Returns: 3711 Successful response 3712 """ 3713 query: dict[str, object] = {} 3714 if limit is not None: 3715 query["limit"] = limit 3716 if after_cursor is not None: 3717 query["after_cursor"] = after_cursor 3718 return self._http.request( 3719 f"/api/v1/orgs/{org}/tasks/blocker_cycles", 3720 query=query, 3721 response_type=OrgTaskBlockerCyclesResponse, 3722 ) 3723 3724 def by_source(self, org: str, input: OrgTaskBySourceInput) -> TaskEnsureResult: 3725 """ 3726 Find or create a task by source 3727 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3728 3729 Args: 3730 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3731 input: Request body. 3732 input.agent: Explicit acting agent for privileged callers. 3733 input.description: Initial task description. 3734 input.epic: Initial epic grouping. 3735 input.name: Initial task name. 3736 input.source_id: Source identity, for example owner/repo#123. 3737 input.source_scope: Source scope, for example github. 3738 input.source_type: Source type, for example pull_request. 3739 input.status: Initial task status. 3740 input.team: Team owner. 3741 input.user: User owner, or explicit acting user on a team route. 3742 3743 Returns: 3744 The task and whether this request created it. 3745 """ 3746 return self._http.request( 3747 f"/api/v1/orgs/{org}/tasks/by-source", 3748 method="PUT", 3749 body=input, 3750 response_type=TaskEnsureResult, 3751 ) 3752 3753 def metrics(self, org: str, *, days: int | None = None) -> OrgTaskMetricsResponse: 3754 """ 3755 Get task activity metrics for an organization 3756 Returns task activity metrics scoped to org-owned tasks (org tenant, no 3757 narrower user/team/agent scope). `open` counts currently open or 3758 in-progress org tasks, `created` counts tasks inserted in the UTC-day 3759 window, and `completed` counts tasks whose `closed_at` falls in that window 3760 while still in a closed status. Hard-deleted tasks are absent from the 3761 projection and therefore omitted. The daily series is zero-filled across 3762 the requested window and includes reconstructed end-of-day `open` stock. 3763 Any organization member may read this count-only summary. Requests from 3764 callers without org access return 404 so organization existence is not 3765 disclosed. 3766 3767 Args: 3768 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3769 days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30. 3770 3771 Returns: 3772 Successful response 3773 """ 3774 query: dict[str, object] = {} 3775 if days is not None: 3776 query["days"] = days 3777 return self._http.request( 3778 f"/api/v1/orgs/{org}/tasks/metrics", 3779 query=query, 3780 response_type=OrgTaskMetricsResponse, 3781 ) 3782 3783 def ready( 3784 self, 3785 org: str, 3786 *, 3787 explain: bool | None = None, 3788 assigned_to_me: bool | None = None, 3789 source_scope: str | None = None, 3790 source_type: str | None = None, 3791 source_id: str | None = None, 3792 epic: str | None = None, 3793 limit: int | None = None, 3794 after_cursor: str | None = None, 3795 ) -> OrgTaskReadyResponse: 3796 """ 3797 List an organization's ready tasks 3798 Returns open org-owned tasks with no unfinished blockers and no active 3799 session lease. Readiness is calculated by the server from the current task 3800 projection. It is a snapshot, not a reservation; claim a task lease before 3801 starting work. 3802 Results are ordered by priority (0, the most urgent, first), then oldest 3803 first, so the first page is always the most urgent ready work. 3804 Pass `explain=true` to include every open task with a stable readiness reason. 3805 3806 Args: 3807 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3808 explain: Include blocked and actively leased open tasks with exclusion reasons. 3809 assigned_to_me: Only include tasks assigned to the authenticated user. 3810 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3811 source_type: Only include tasks whose source matches this object kind. 3812 source_id: Only include tasks whose source matches this object identity. 3813 epic: Only include tasks with this exact epic label. 3814 limit: Maximum number of readiness entries to return. Capped at 100. 3815 after_cursor: Opaque cursor returned by the previous page. 3816 3817 Returns: 3818 Successful response 3819 """ 3820 query: dict[str, object] = {} 3821 if explain is not None: 3822 query["explain"] = explain 3823 if assigned_to_me is not None: 3824 query["assigned_to_me"] = assigned_to_me 3825 if source_scope is not None: 3826 query["source_scope"] = source_scope 3827 if source_type is not None: 3828 query["source_type"] = source_type 3829 if source_id is not None: 3830 query["source_id"] = source_id 3831 if epic is not None: 3832 query["epic"] = epic 3833 if limit is not None: 3834 query["limit"] = limit 3835 if after_cursor is not None: 3836 query["after_cursor"] = after_cursor 3837 return self._http.request( 3838 f"/api/v1/orgs/{org}/tasks/ready", 3839 query=query, 3840 response_type=OrgTaskReadyResponse, 3841 ) 3842 3843 def search( 3844 self, 3845 org: str, 3846 *, 3847 q: str | None = None, 3848 query: str | None = None, 3849 status: str | None = None, 3850 owner_user: str | None = None, 3851 owner_agent: str | None = None, 3852 priority: int | None = None, 3853 tag: str | None = None, 3854 parent: str | None = None, 3855 source_scope: str | None = None, 3856 source_type: str | None = None, 3857 source_id: str | None = None, 3858 epic: str | None = None, 3859 limit: int | None = None, 3860 after_cursor: str | None = None, 3861 ) -> OrgTaskSearchResponse: 3862 """ 3863 Search an organization's tasks 3864 Performs a full-text search over org-owned tasks for the specified 3865 organization and returns matching results. Combine `q` with the optional 3866 filters to narrow the result set further. When no query is provided, the 3867 endpoint behaves like a filtered list. 3868 The `query` field in the response echoes the effective search query. 3869 Explicitly personal, team, or agent tasks are excluded here. 3870 3871 Args: 3872 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3873 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3874 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3875 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3876 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3877 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3878 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3879 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3880 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3881 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3882 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3883 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3884 epic: Return only tasks with this exact epic label. 3885 limit: Maximum number of tasks to return. Capped at 100. 3886 after_cursor: Opaque cursor returned by the previous page. 3887 3888 Returns: 3889 Successful response 3890 """ 3891 query: dict[str, object] = {} 3892 if q is not None: 3893 query["q"] = q 3894 if query is not None: 3895 query["query"] = query 3896 if status is not None: 3897 query["status"] = status 3898 if owner_user is not None: 3899 query["owner_user"] = owner_user 3900 if owner_agent is not None: 3901 query["owner_agent"] = owner_agent 3902 if priority is not None: 3903 query["priority"] = priority 3904 if tag is not None: 3905 query["tag"] = tag 3906 if parent is not None: 3907 query["parent"] = parent 3908 if source_scope is not None: 3909 query["source_scope"] = source_scope 3910 if source_type is not None: 3911 query["source_type"] = source_type 3912 if source_id is not None: 3913 query["source_id"] = source_id 3914 if epic is not None: 3915 query["epic"] = epic 3916 if limit is not None: 3917 query["limit"] = limit 3918 if after_cursor is not None: 3919 query["after_cursor"] = after_cursor 3920 return self._http.request( 3921 f"/api/v1/orgs/{org}/tasks/search", 3922 query=query, 3923 response_type=OrgTaskSearchResponse, 3924 ) 3925 3926 3927class OrgThreadResource: 3928 def __init__(self, http: SyncHttpClient): 3929 self._http = http 3930 3931 def list(self, org: str, *, key: str | None = None) -> OrgThreadListResponse: 3932 """ 3933 List organization-visibility threads 3934 Returns org-visibility threads for the specified organization. Every member 3935 of the organization can list these threads; they require no team membership. 3936 App-scoped developer tokens for the organization's app can list them too. 3937 3938 Args: 3939 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3940 key: Optional exact thread key, for example `support-room`. 3941 3942 Returns: 3943 Successful response 3944 """ 3945 query: dict[str, object] = {} 3946 if key is not None: 3947 query["key"] = key 3948 return self._http.request( 3949 f"/api/v1/orgs/{org}/threads", 3950 query=query, 3951 response_type=OrgThreadListResponse, 3952 ) 3953 3954 def create(self, org: str, input: OrgThreadCreateInput) -> Thread: 3955 """ 3956 Create an organization-visibility thread 3957 Creates a thread owned by the organization rather than a team, user, or agent. 3958 Every member of the organization can read and post without joining. The 3959 authenticated caller must be an organization administrator, or use an 3960 app-scoped developer token for the organization's app. 3961 When `thread.key` is supplied, creation is idempotent: a second call with the 3962 same key returns the existing org-visibility thread instead of inserting a 3963 duplicate. 3964 3965 Args: 3966 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3967 input: Request body. 3968 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3969 input.thread: Attributes for the new thread. Visibility is forced to `org`. 3970 3971 Returns: 3972 The organization-visibility thread. 3973 """ 3974 return self._http.request( 3975 f"/api/v1/orgs/{org}/threads", 3976 method="POST", 3977 body=input, 3978 response_type=Thread, 3979 ) 3980 3981 3982class OrgResource: 3983 def __init__(self, http: SyncHttpClient): 3984 self._http = http 3985 self.tasks = OrgTaskResource(http) 3986 self.threads = OrgThreadResource(http) 3987 3988 def list( 3989 self, *, search: str | None = None, page: int | None = None, page_size: int | None = None 3990 ) -> OrgListResponse: 3991 """ 3992 Search organizations 3993 Returns a paginated list of organizations within the authenticated app scope, 3994 optionally filtered by a free-text search term matched against name, slug, and 3995 domain (case-insensitive). Results are ordered by relevance when a search term 3996 is provided, and by creation time descending otherwise. 3997 The response includes only public-facing organization fields: ID, name, domain, 3998 and logo. Use the developer-scoped org endpoints to access full organization 3999 records. 4000 Pagination is offset-based. Pass `page` and `page_size` to navigate through 4001 results. The `has_next` and `has_prev` fields indicate whether adjacent pages 4002 exist. 4003 4004 Args: 4005 search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app. 4006 page: Page number to retrieve, starting at `1`. Defaults to `1` when omitted. 4007 page_size: Number of organizations to return per page. Defaults to `25`; maximum is `100`. 4008 4009 Returns: 4010 Successful response 4011 """ 4012 query: dict[str, object] = {} 4013 if search is not None: 4014 query["search"] = search 4015 if page is not None: 4016 query["page"] = page 4017 if page_size is not None: 4018 query["page_size"] = page_size 4019 return self._http.request("/api/v1/orgs", query=query, response_type=OrgListResponse) 4020 4021 def artifacts( 4022 self, 4023 org: str, 4024 *, 4025 limit: int | None = None, 4026 after_cursor: str | None = None, 4027 group_key: str | None = None, 4028 group_key_prefix: str | None = None, 4029 ) -> OrgArtifactsResponse: 4030 """ 4031 List completed organization artifacts 4032 Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded. 4033 4034 Args: 4035 org: Organization ID. 4036 limit: Maximum snapshots returned, from 1 to 100. 4037 after_cursor: Opaque cursor for the next page of older snapshots. 4038 group_key: Exact, case-sensitive grouping key. 4039 group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key. 4040 4041 Returns: 4042 Successful response 4043 """ 4044 query: dict[str, object] = {} 4045 if limit is not None: 4046 query["limit"] = limit 4047 if after_cursor is not None: 4048 query["after_cursor"] = after_cursor 4049 if group_key is not None: 4050 query["group_key"] = group_key 4051 if group_key_prefix is not None: 4052 query["group_key_prefix"] = group_key_prefix 4053 return self._http.request( 4054 f"/api/v1/orgs/{org}/artifacts", 4055 query=query, 4056 response_type=OrgArtifactsResponse, 4057 ) 4058 4059 def linked_accounts( 4060 self, 4061 org: str, 4062 *, 4063 user: builtins.list[str] | None = None, 4064 limit: int | None = None, 4065 after_cursor: str | None = None, 4066 ) -> OrgLinkedAccountsResponse: 4067 """ 4068 List an organization's linked accounts 4069 Returns the GitHub login each user in the organization signed in with, so 4070 clients can tell that a pull request's author and a Platform user are the 4071 same person. Users who never signed in with GitHub are absent. Any viewer 4072 acting within the organization can list them; other viewers get 404. 4073 Pass `user` to look up specific users instead of listing the whole 4074 organization. Results are ordered by user and paginated forward with 4075 `after_cursor`. 4076 4077 Args: 4078 org: Organization ID (`org_...`) whose linked accounts should be listed. 4079 user: Up to 100 user IDs (`usr_...`) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. 4080 limit: Maximum accounts returned, from 1 to 100. 4081 after_cursor: Opaque cursor for the next page. 4082 4083 Returns: 4084 Successful response 4085 """ 4086 query: dict[str, object] = {} 4087 if user is not None: 4088 query["user"] = user 4089 if limit is not None: 4090 query["limit"] = limit 4091 if after_cursor is not None: 4092 query["after_cursor"] = after_cursor 4093 return self._http.request( 4094 f"/api/v1/orgs/{org}/linked_accounts", 4095 query=query, 4096 response_type=OrgLinkedAccountsResponse, 4097 ) 4098 4099 def task_epics( 4100 self, 4101 org: str, 4102 *, 4103 source_scope: str | None = None, 4104 source_type: str | None = None, 4105 source_id: str | None = None, 4106 top_priority: int | None = None, 4107 include_closed: bool | None = None, 4108 limit: int | None = None, 4109 after_cursor: str | None = None, 4110 ) -> OrgTaskEpicsResponse: 4111 """ 4112 List an organization's epic summaries 4113 Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 4114 4115 Args: 4116 org: Organization ID (`org_...`) owning the tasks. 4117 source_scope: Exact source scope; supply all three source fields. 4118 source_type: Exact source type. 4119 source_id: Exact source ID. 4120 top_priority: Exact highest open priority, from 0 to 4. 4121 include_closed: Include epics with no non-closed tasks; defaults to false. 4122 limit: Maximum epics; defaults to 50, capped at 100. 4123 after_cursor: Opaque forward cursor from the preceding page. 4124 4125 Returns: 4126 Successful response 4127 """ 4128 query: dict[str, object] = {} 4129 if source_scope is not None: 4130 query["source_scope"] = source_scope 4131 if source_type is not None: 4132 query["source_type"] = source_type 4133 if source_id is not None: 4134 query["source_id"] = source_id 4135 if top_priority is not None: 4136 query["top_priority"] = top_priority 4137 if include_closed is not None: 4138 query["include_closed"] = include_closed 4139 if limit is not None: 4140 query["limit"] = limit 4141 if after_cursor is not None: 4142 query["after_cursor"] = after_cursor 4143 return self._http.request( 4144 f"/api/v1/orgs/{org}/task_epics", 4145 query=query, 4146 response_type=OrgTaskEpicsResponse, 4147 )
class
OrgTaskCreateInputTask(typing.TypedDict):
19class OrgTaskCreateInputTask(TypedDict, total=False): 20 description: str | None 21 "Optional long-form description or notes for the task. Supports plain text." 22 due_date: datetime | None 23 "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." 24 epic: str | None 25 "Optional free-form grouping label." 26 id: str | None 27 "Optional caller-generated task public ID (`tsk_...`). Persist it before creating a task when creation must survive a lost response. An existing ID returns 409 without modifying the task; read the task by ID to reconcile. Omit for a server-generated ID." 28 links: dict[str, Any] | None 29 "Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links)." 30 metadata: dict[str, Any] | None 31 "Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata." 32 name: Required[str] 33 "Human-readable title for the task." 34 owner_agent: str | None 35 "ID of the agent to assign as owner (`agi_...`). Mutually exclusive with `owner_user`; omit to leave the task unassigned." 36 owner_user: str | None 37 "ID of the user to assign as owner (`usr_...`). Mutually exclusive with `owner_agent`; omit to leave the task unassigned." 38 parent: str | None 39 "Create this task as a subtask of an existing top-level task (`tsk_...`). Subtasks nest exactly one level." 40 priority: int | None 41 "Priority level from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when omitted." 42 project_id: str | None 43 "Optional project ID (`prj_...`). Pass null to clear it." 44 source_id: str | None 45 "Source object identity (for example `ArchAstro/firstlanding`)." 46 source_scope: str | None 47 "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`." 48 source_type: str | None 49 "Kind of source object (for example `repository`)." 50 status: str | None 51 'Initial status for the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`. Defaults to `"open"` when omitted.' 52 tags: list[str] | None 53 "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated." 54 target_binary: str | None 55 "Binary that must run this work, as a lowercase identifier of 1-64 characters (letters, digits, `.`, `_`, `-`; for example `my-cli`). Must be supplied with `target_version`." 56 target_version: str | None 57 "Minimum semantic version of `target_binary` that can run this work (`MAJOR.MINOR.PATCH` with optional prerelease and build, no leading `v`). Must be supplied with `target_binary`." 58 thread: str | None 59 "Bind the task to a thread (`thr_...`) owned by the same team or user as the task. A bound task appears in that thread's task scope, exactly like a task filed from inside the conversation. Omit for a task not tied to a conversation."
due_date: datetime.datetime | None
Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date.
id: str | None
Optional caller-generated task public ID (tsk_...). Persist it before creating a task when creation must survive a lost response. An existing ID returns 409 without modifying the task; read the task by ID to reconcile. Omit for a server-generated ID.
links: dict[str, typing.Any] | None
Arbitrary key-value map of named URLs or references associated with the task (e.g. external ticket links).
metadata: dict[str, typing.Any] | None
Arbitrary key-value map for storing application-specific data alongside the task. Omit to create the task with no metadata.
owner_agent: str | None
ID of the agent to assign as owner (agi_...). Mutually exclusive with owner_user; omit to leave the task unassigned.
owner_user: str | None
ID of the user to assign as owner (usr_...). Mutually exclusive with owner_agent; omit to leave the task unassigned.
parent: str | None
Create this task as a subtask of an existing top-level task (tsk_...). Subtasks nest exactly one level.
priority: int | None
Priority level from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when omitted.
source_scope: str | None
Container of the work this task is about (for example github.com). Must be supplied with source_type and source_id.
status: str | None
Initial status for the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled". Defaults to "open" when omitted.
target_binary: str | None
Binary that must run this work, as a lowercase identifier of 1-64 characters (letters, digits, ., _, -; for example my-cli). Must be supplied with target_version.
target_version: str | None
Minimum semantic version of target_binary that can run this work (MAJOR.MINOR.PATCH with optional prerelease and build, no leading v). Must be supplied with target_binary.
class
OrgTaskCreateInput(typing.TypedDict):
62class OrgTaskCreateInput(TypedDict, total=False): 63 "Create a task for an organization" 64 65 agent: str | None 66 "Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization." 67 task: Required[OrgTaskCreateInputTask] 68 "Attributes for the task to create. `name` is required; all other fields are optional." 69 user: str | None 70 "Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`."
Create a task for an organization
agent: str | None
Explicit acting agent (agi_...) for a developer or server-to-server call. Mutually exclusive with an acting user; the agent must belong to the organization.
task: Required[OrgTaskCreateInputTask]
Attributes for the task to create. name is required; all other fields are optional.
user: str | None
Explicit acting user (usr_...) for a developer or server-to-server call. Mutually exclusive with an acting agent.
class
OrgTaskBySourceInput(typing.TypedDict):
73class OrgTaskBySourceInput(TypedDict, total=False): 74 "Find or create a task by source" 75 76 agent: str | None 77 "Explicit acting agent for privileged callers." 78 description: str | None 79 "Initial task description." 80 epic: str | None 81 "Initial epic grouping." 82 name: Required[str] 83 "Initial task name." 84 source_id: Required[str] 85 "Source identity, for example owner/repo#123." 86 source_scope: Required[str] 87 "Source scope, for example github." 88 source_type: Required[str] 89 "Source type, for example pull_request." 90 status: str | None 91 "Initial task status." 92 team: str | None 93 "Team owner." 94 user: str | None 95 "User owner, or explicit acting user on a team route."
Find or create a task by source
class
OrgThreadCreateInputThreadMembersItem(typing.TypedDict):
class
OrgThreadCreateInputThreadProfilePicture(typing.TypedDict):
105class OrgThreadCreateInputThreadProfilePicture(TypedDict, total=False): 106 data: str | None 107 "Base64-encoded image bytes." 108 filename: str | None 109 "Original filename of the uploaded image, used for display and content-type inference." 110 mime_type: str | None 111 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.'
class
OrgThreadCreateInputThreadSettings(typing.TypedDict):
114class OrgThreadCreateInputThreadSettings(TypedDict, total=False): 115 agent_enabled: bool | None 116 "Whether the AI agent is active for this thread. `true` enables AI responses; `false` disables them. Defaults to `true` when settings have not been explicitly configured. `null` when a client explicitly cleared the setting."
class
OrgThreadCreateInputThread(typing.TypedDict):
119class OrgThreadCreateInputThread(TypedDict, total=False): 120 create_legacy_agent: bool | None 121 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 122 description: str | None 123 "Optional longer description of the thread's purpose. `null` if not provided." 124 is_unlisted: bool | None 125 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 126 key: str | None 127 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 128 kind: Literal["personal", "feed"] | None 129 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. `feed` is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers." 130 members: list[OrgThreadCreateInputThreadMembersItem] | None 131 "Users and agents to add atomically when the thread is created. Each target must pass the same authorization rules as a post-creation member add. Slack mirror threads reject non-empty caller-supplied rosters because their membership is sync-owned." 132 metadata: dict[str, Any] | None 133 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 134 muted: bool | None 135 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 136 org_id: str | None 137 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 138 profile_picture: OrgThreadCreateInputThreadProfilePicture | None 139 "Optional profile image for the thread, provided as a base64-encoded payload." 140 settings: OrgThreadCreateInputThreadSettings | None 141 "Configuration overrides for the thread, such as AI model selection and context window settings." 142 slug: str | None 143 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 144 title: str | None 145 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 146 visibility: Literal["team", "restricted", "private", "org"] | None 147 "Thread visibility. A team-owned thread with members must explicitly use `restricted` or `private`. User- and agent-owned threads with members default to `private` and reject every other value. `org` is only valid on an organization-owned thread with no team, user, or agent owner."
create_legacy_agent: bool | None
When true, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model.
is_unlisted: bool | None
When true, the thread is hidden from the default thread list and accessible only by direct link or ID.
key: str | None
Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization.
kind: Optional[Literal['personal', 'feed']]
Optional behavioral subtype. personal is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. feed is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers.
members: list[OrgThreadCreateInputThreadMembersItem] | None
Users and agents to add atomically when the thread is created. Each target must pass the same authorization rules as a post-creation member add. Slack mirror threads reject non-empty caller-supplied rosters because their membership is sync-owned.
metadata: dict[str, typing.Any] | None
Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers.
muted: bool | None
When true, push and in-app notifications for this thread are suppressed for the creating user.
org_id: str | None
ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted.
profile_picture: OrgThreadCreateInputThreadProfilePicture | None
Optional profile image for the thread, provided as a base64-encoded payload.
settings: OrgThreadCreateInputThreadSettings | None
Configuration overrides for the thread, such as AI model selection and context window settings.
slug: str | None
Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner.
title: str | None
Display name for the thread. null if omitted, which causes the thread to be untitled.
visibility: Optional[Literal['team', 'restricted', 'private', 'org']]
Thread visibility. A team-owned thread with members must explicitly use restricted or private. User- and agent-owned threads with members default to private and reject every other value. org is only valid on an organization-owned thread with no team, user, or agent owner.
class
OrgThreadCreateInput(typing.TypedDict):
150class OrgThreadCreateInput(TypedDict, total=False): 151 "Create an organization-visibility thread" 152 153 skip_welcome_message: bool | None 154 "When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`." 155 thread: Required[OrgThreadCreateInputThread] 156 "Attributes for the new thread. Visibility is forced to `org`."
Create an organization-visibility thread
skip_welcome_message: bool | None
When true, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to false.
thread: Required[OrgThreadCreateInputThread]
Attributes for the new thread. Visibility is forced to org.
class
OrgTaskListResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
159class OrgTaskListResponseDataItemCreatedByActorProfilePicture(BaseModel): 160 file: str | None = Field( 161 default=None, 162 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 163 ) 164 height: int | None = Field( 165 default=None, description="Height of the image in pixels. `null` if not known." 166 ) 167 media: str | None = Field( 168 default=None, 169 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 170 ) 171 mime_type: str | None = Field( 172 default=None, 173 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 174 ) 175 refresh_url: str | None = Field( 176 default=None, 177 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.", 178 ) 179 url: str | None = Field( 180 default=None, 181 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.", 182 ) 183 width: int | None = Field( 184 default=None, description="Width of the image in pixels. `null` if not known." 185 )
!!! 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
OrgTaskListResponseDataItemCreatedByActor(pydantic.main.BaseModel):
188class OrgTaskListResponseDataItemCreatedByActor(BaseModel): 189 alias: str | None = Field( 190 default=None, 191 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 192 ) 193 id: str | None = Field( 194 default=None, 195 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 196 ) 197 name: str | None = Field( 198 default=None, 199 description="Display name of the actor shown in the UI. `null` if no name is set.", 200 ) 201 profile_picture: OrgTaskListResponseDataItemCreatedByActorProfilePicture | None = Field( 202 default=None, 203 description="Profile picture for the actor. `null` if the actor has no profile picture.", 204 )
!!! 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
OrgTaskListResponseDataItemCurrentLease(pydantic.main.BaseModel):
207class OrgTaskListResponseDataItemCurrentLease(BaseModel): 208 expires_at: datetime = Field( 209 ..., description="Server-calculated lease expiry in ISO 8601 format." 210 ) 211 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 212 session_name: str = Field( 213 ..., description="Display name supplied by the coding session that holds the lease." 214 )
!!! 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
OrgTaskListResponseDataItemOwnerActorProfilePicture(pydantic.main.BaseModel):
217class OrgTaskListResponseDataItemOwnerActorProfilePicture(BaseModel): 218 file: str | None = Field( 219 default=None, 220 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 221 ) 222 height: int | None = Field( 223 default=None, description="Height of the image in pixels. `null` if not known." 224 ) 225 media: str | None = Field( 226 default=None, 227 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 228 ) 229 mime_type: str | None = Field( 230 default=None, 231 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 232 ) 233 refresh_url: str | None = Field( 234 default=None, 235 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.", 236 ) 237 url: str | None = Field( 238 default=None, 239 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.", 240 ) 241 width: int | None = Field( 242 default=None, description="Width of the image in pixels. `null` if not known." 243 )
!!! 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
OrgTaskListResponseDataItemOwnerActor(pydantic.main.BaseModel):
246class OrgTaskListResponseDataItemOwnerActor(BaseModel): 247 alias: str | None = Field( 248 default=None, 249 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 250 ) 251 id: str | None = Field( 252 default=None, 253 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 254 ) 255 name: str | None = Field( 256 default=None, 257 description="Display name of the actor shown in the UI. `null` if no name is set.", 258 ) 259 profile_picture: OrgTaskListResponseDataItemOwnerActorProfilePicture | None = Field( 260 default=None, 261 description="Profile picture for the actor. `null` if the actor has no profile picture.", 262 )
!!! 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
OrgTaskListResponseDataItem(pydantic.main.BaseModel):
265class OrgTaskListResponseDataItem(BaseModel): 266 agent: str | None = Field( 267 default=None, 268 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 269 ) 270 aggregate_version: int | None = Field( 271 default=None, 272 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 273 ) 274 blocked_by_count: int | None = Field( 275 default=None, 276 description="Number of readable 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.", 277 ) 278 closed_at: datetime | None = Field( 279 default=None, 280 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 281 ) 282 comments_count: int | None = Field( 283 default=None, description="Total number of comments posted on this task." 284 ) 285 created_at: datetime | None = Field( 286 default=None, description="When the task was created (ISO 8601)." 287 ) 288 created_by_actor: OrgTaskListResponseDataItemCreatedByActor | None = Field( 289 default=None, 290 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).", 291 ) 292 created_by_agent: str | None = Field( 293 default=None, 294 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.", 295 ) 296 created_by_user: str | None = Field( 297 default=None, 298 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.", 299 ) 300 current_lease: OrgTaskListResponseDataItemCurrentLease | None = Field( 301 default=None, 302 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.", 303 ) 304 description: str | None = Field( 305 default=None, 306 description="Long-form description or notes for the task. `null` if no description has been provided.", 307 ) 308 due_date: datetime | None = Field( 309 default=None, 310 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 311 ) 312 epic: str | None = Field( 313 default=None, 314 description="Free-form grouping label. `null` when the task is not in an epic.", 315 ) 316 id: str = Field(..., description="Task ID (`tsk_...`).") 317 is_blocked: bool | None = Field( 318 default=None, 319 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 reads, including mutation responses.", 320 ) 321 is_stalled: bool | None = Field( 322 default=None, 323 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 324 ) 325 links: dict[str, Any] | None = Field( 326 default=None, 327 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 328 ) 329 metadata: dict[str, Any] | None = Field( 330 default=None, 331 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 332 ) 333 name: str = Field(..., description="Human-readable title of the task.") 334 org: str | None = Field( 335 default=None, 336 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 337 ) 338 owner_actor: OrgTaskListResponseDataItemOwnerActor | None = Field( 339 default=None, 340 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).", 341 ) 342 owner_agent: str | None = Field( 343 default=None, 344 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.", 345 ) 346 owner_user: str | None = Field( 347 default=None, 348 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.", 349 ) 350 parent: str | None = Field( 351 default=None, 352 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 353 ) 354 priority: int | None = Field( 355 default=None, 356 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 357 ) 358 project_id: str | None = Field( 359 default=None, 360 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 361 ) 362 sandbox: str | None = Field( 363 default=None, 364 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 365 ) 366 source_id: str | None = Field( 367 default=None, 368 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 369 ) 370 source_scope: str | None = Field( 371 default=None, 372 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`.", 373 ) 374 source_type: str | None = Field( 375 default=None, 376 description="Kind of source object (for example `repository`). `null` when the task has no source.", 377 ) 378 stalled_since: datetime | None = Field( 379 default=None, 380 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 381 ) 382 status: str = Field( 383 ..., 384 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 385 ) 386 subtasks_count: int | None = Field( 387 default=None, 388 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 389 ) 390 tags: list[str] | None = Field( 391 default=None, 392 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 393 ) 394 target_binary: str | None = Field( 395 default=None, 396 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 397 ) 398 target_version: str | None = Field( 399 default=None, 400 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 401 ) 402 team: str | None = Field( 403 default=None, 404 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 405 ) 406 thread: str | None = Field( 407 default=None, 408 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.", 409 ) 410 updated_at: datetime | None = Field( 411 default=None, description="When the task was last modified (ISO 8601)." 412 ) 413 user: str | None = Field( 414 default=None, 415 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 416 )
!!! 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.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable 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 reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
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 or when the parent is not readable. 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.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
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.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
OrgTaskListResponse(pydantic.main.BaseModel):
419class OrgTaskListResponse(BaseModel): 420 """ 421 Successful response 422 """ 423 424 after_cursor: str | None = None 425 before_cursor: str | None = None 426 data: list[OrgTaskListResponseDataItem] = Field( 427 ..., description="Array of task objects matching the requested filters." 428 ) 429 has_more: bool
Successful response
class
OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
432class OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(BaseModel): 433 file: str | None = Field( 434 default=None, 435 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 436 ) 437 height: int | None = Field( 438 default=None, description="Height of the image in pixels. `null` if not known." 439 ) 440 media: str | None = Field( 441 default=None, 442 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 443 ) 444 mime_type: str | None = Field( 445 default=None, 446 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 447 ) 448 refresh_url: str | None = Field( 449 default=None, 450 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.", 451 ) 452 url: str | None = Field( 453 default=None, 454 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.", 455 ) 456 width: int | None = Field( 457 default=None, description="Width of the image in pixels. `null` if not known." 458 )
!!! 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
OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(pydantic.main.BaseModel):
461class OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(BaseModel): 462 alias: str | None = Field( 463 default=None, 464 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 465 ) 466 id: str | None = Field( 467 default=None, 468 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 469 ) 470 name: str | None = Field( 471 default=None, 472 description="Display name of the actor shown in the UI. `null` if no name is set.", 473 ) 474 profile_picture: ( 475 OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None 476 ) = Field( 477 default=None, 478 description="Profile picture for the actor. `null` if the actor has no profile picture.", 479 )
!!! 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.
profile_picture: OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None =
None
Profile picture for the actor. null if the actor has no profile picture.
class
OrgTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(pydantic.main.BaseModel):
482class OrgTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(BaseModel): 483 expires_at: datetime = Field( 484 ..., description="Server-calculated lease expiry in ISO 8601 format." 485 ) 486 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 487 session_name: str = Field( 488 ..., description="Display name supplied by the coding session that holds the lease." 489 )
!!! 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
OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(pydantic.main.BaseModel):
492class OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(BaseModel): 493 file: str | None = Field( 494 default=None, 495 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 496 ) 497 height: int | None = Field( 498 default=None, description="Height of the image in pixels. `null` if not known." 499 ) 500 media: str | None = Field( 501 default=None, 502 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 503 ) 504 mime_type: str | None = Field( 505 default=None, 506 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 507 ) 508 refresh_url: str | None = Field( 509 default=None, 510 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.", 511 ) 512 url: str | None = Field( 513 default=None, 514 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.", 515 ) 516 width: int | None = Field( 517 default=None, description="Width of the image in pixels. `null` if not known." 518 )
!!! 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
OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(pydantic.main.BaseModel):
521class OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(BaseModel): 522 alias: str | None = Field( 523 default=None, 524 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 525 ) 526 id: str | None = Field( 527 default=None, 528 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 529 ) 530 name: str | None = Field( 531 default=None, 532 description="Display name of the actor shown in the UI. `null` if no name is set.", 533 ) 534 profile_picture: ( 535 OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None 536 ) = Field( 537 default=None, 538 description="Profile picture for the actor. `null` if the actor has no profile picture.", 539 )
!!! 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.
profile_picture: OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None =
None
Profile picture for the actor. null if the actor has no profile picture.
class
OrgTaskBlockerCyclesResponseDataItemTasksItem(pydantic.main.BaseModel):
542class OrgTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): 543 agent: str | None = Field( 544 default=None, 545 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 546 ) 547 aggregate_version: int | None = Field( 548 default=None, 549 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 550 ) 551 blocked_by_count: int | None = Field( 552 default=None, 553 description="Number of readable 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.", 554 ) 555 closed_at: datetime | None = Field( 556 default=None, 557 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 558 ) 559 comments_count: int | None = Field( 560 default=None, description="Total number of comments posted on this task." 561 ) 562 created_at: datetime | None = Field( 563 default=None, description="When the task was created (ISO 8601)." 564 ) 565 created_by_actor: OrgTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor | None = Field( 566 default=None, 567 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).", 568 ) 569 created_by_agent: str | None = Field( 570 default=None, 571 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.", 572 ) 573 created_by_user: str | None = Field( 574 default=None, 575 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.", 576 ) 577 current_lease: OrgTaskBlockerCyclesResponseDataItemTasksItemCurrentLease | None = Field( 578 default=None, 579 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.", 580 ) 581 description: str | None = Field( 582 default=None, 583 description="Long-form description or notes for the task. `null` if no description has been provided.", 584 ) 585 due_date: datetime | None = Field( 586 default=None, 587 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 588 ) 589 epic: str | None = Field( 590 default=None, 591 description="Free-form grouping label. `null` when the task is not in an epic.", 592 ) 593 id: str = Field(..., description="Task ID (`tsk_...`).") 594 is_blocked: bool | None = Field( 595 default=None, 596 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 reads, including mutation responses.", 597 ) 598 is_stalled: bool | None = Field( 599 default=None, 600 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 601 ) 602 links: dict[str, Any] | None = Field( 603 default=None, 604 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 605 ) 606 metadata: dict[str, Any] | None = Field( 607 default=None, 608 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 609 ) 610 name: str = Field(..., description="Human-readable title of the task.") 611 org: str | None = Field( 612 default=None, 613 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 614 ) 615 owner_actor: OrgTaskBlockerCyclesResponseDataItemTasksItemOwnerActor | None = Field( 616 default=None, 617 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).", 618 ) 619 owner_agent: str | None = Field( 620 default=None, 621 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.", 622 ) 623 owner_user: str | None = Field( 624 default=None, 625 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.", 626 ) 627 parent: str | None = Field( 628 default=None, 629 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 630 ) 631 priority: int | None = Field( 632 default=None, 633 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 634 ) 635 project_id: str | None = Field( 636 default=None, 637 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 638 ) 639 sandbox: str | None = Field( 640 default=None, 641 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 642 ) 643 source_id: str | None = Field( 644 default=None, 645 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 646 ) 647 source_scope: str | None = Field( 648 default=None, 649 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`.", 650 ) 651 source_type: str | None = Field( 652 default=None, 653 description="Kind of source object (for example `repository`). `null` when the task has no source.", 654 ) 655 stalled_since: datetime | None = Field( 656 default=None, 657 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 658 ) 659 status: str = Field( 660 ..., 661 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 662 ) 663 subtasks_count: int | None = Field( 664 default=None, 665 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 666 ) 667 tags: list[str] | None = Field( 668 default=None, 669 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 670 ) 671 target_binary: str | None = Field( 672 default=None, 673 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 674 ) 675 target_version: str | None = Field( 676 default=None, 677 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 678 ) 679 team: str | None = Field( 680 default=None, 681 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 682 ) 683 thread: str | None = Field( 684 default=None, 685 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.", 686 ) 687 updated_at: datetime | None = Field( 688 default=None, description="When the task was last modified (ISO 8601)." 689 ) 690 user: str | None = Field( 691 default=None, 692 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 693 )
!!! 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.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable 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 reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
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 or when the parent is not readable. 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.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
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.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
OrgTaskBlockerCyclesResponseDataItem(pydantic.main.BaseModel):
696class OrgTaskBlockerCyclesResponseDataItem(BaseModel): 697 tasks: list[OrgTaskBlockerCyclesResponseDataItemTasksItem] = Field( 698 ..., description="Every unfinished task in this cyclic blocker component." 699 )
!!! 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
OrgTaskBlockerCyclesResponse(pydantic.main.BaseModel):
702class OrgTaskBlockerCyclesResponse(BaseModel): 703 """ 704 Successful response 705 """ 706 707 after_cursor: str | None = None 708 before_cursor: str | None = None 709 data: list[OrgTaskBlockerCyclesResponseDataItem] 710 has_more: bool
Successful response
class
OrgTaskMetricsResponse(pydantic.main.BaseModel):
713class OrgTaskMetricsResponse(BaseModel): 714 """ 715 Successful response 716 """ 717 718 completed: int 719 created: int 720 days: int 721 end_at: datetime 722 open: int 723 series: list[dict[str, Any]] = Field( 724 ..., 725 description="Zero-filled UTC-day buckets with `date`, end-of-day `open`, `created`, and `completed`.", 726 ) 727 start_at: datetime
Successful response
class
OrgTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(pydantic.main.BaseModel):
730class OrgTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): 731 file: str | None = Field( 732 default=None, 733 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 734 ) 735 height: int | None = Field( 736 default=None, description="Height of the image in pixels. `null` if not known." 737 ) 738 media: str | None = Field( 739 default=None, 740 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 741 ) 742 mime_type: str | None = Field( 743 default=None, 744 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 745 ) 746 refresh_url: str | None = Field( 747 default=None, 748 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.", 749 ) 750 url: str | None = Field( 751 default=None, 752 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.", 753 ) 754 width: int | None = Field( 755 default=None, description="Width of the image in pixels. `null` if not known." 756 )
!!! 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
OrgTaskReadyResponseDataItemTaskCreatedByActor(pydantic.main.BaseModel):
759class OrgTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): 760 alias: str | None = Field( 761 default=None, 762 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 763 ) 764 id: str | None = Field( 765 default=None, 766 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 767 ) 768 name: str | None = Field( 769 default=None, 770 description="Display name of the actor shown in the UI. `null` if no name is set.", 771 ) 772 profile_picture: OrgTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( 773 default=None, 774 description="Profile picture for the actor. `null` if the actor has no profile picture.", 775 )
!!! 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
OrgTaskReadyResponseDataItemTaskCurrentLease(pydantic.main.BaseModel):
778class OrgTaskReadyResponseDataItemTaskCurrentLease(BaseModel): 779 expires_at: datetime = Field( 780 ..., description="Server-calculated lease expiry in ISO 8601 format." 781 ) 782 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 783 session_name: str = Field( 784 ..., description="Display name supplied by the coding session that holds the lease." 785 )
!!! 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
OrgTaskReadyResponseDataItemTaskOwnerActorProfilePicture(pydantic.main.BaseModel):
788class OrgTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): 789 file: str | None = Field( 790 default=None, 791 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 792 ) 793 height: int | None = Field( 794 default=None, description="Height of the image in pixels. `null` if not known." 795 ) 796 media: str | None = Field( 797 default=None, 798 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 799 ) 800 mime_type: str | None = Field( 801 default=None, 802 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 803 ) 804 refresh_url: str | None = Field( 805 default=None, 806 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.", 807 ) 808 url: str | None = Field( 809 default=None, 810 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.", 811 ) 812 width: int | None = Field( 813 default=None, description="Width of the image in pixels. `null` if not known." 814 )
!!! 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
OrgTaskReadyResponseDataItemTaskOwnerActor(pydantic.main.BaseModel):
817class OrgTaskReadyResponseDataItemTaskOwnerActor(BaseModel): 818 alias: str | None = Field( 819 default=None, 820 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 821 ) 822 id: str | None = Field( 823 default=None, 824 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 825 ) 826 name: str | None = Field( 827 default=None, 828 description="Display name of the actor shown in the UI. `null` if no name is set.", 829 ) 830 profile_picture: OrgTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( 831 default=None, 832 description="Profile picture for the actor. `null` if the actor has no profile picture.", 833 )
!!! 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
OrgTaskReadyResponseDataItemTask(pydantic.main.BaseModel):
836class OrgTaskReadyResponseDataItemTask(BaseModel): 837 agent: str | None = Field( 838 default=None, 839 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 840 ) 841 aggregate_version: int | None = Field( 842 default=None, 843 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 844 ) 845 blocked_by_count: int | None = Field( 846 default=None, 847 description="Number of readable 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.", 848 ) 849 closed_at: datetime | None = Field( 850 default=None, 851 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 852 ) 853 comments_count: int | None = Field( 854 default=None, description="Total number of comments posted on this task." 855 ) 856 created_at: datetime | None = Field( 857 default=None, description="When the task was created (ISO 8601)." 858 ) 859 created_by_actor: OrgTaskReadyResponseDataItemTaskCreatedByActor | None = Field( 860 default=None, 861 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).", 862 ) 863 created_by_agent: str | None = Field( 864 default=None, 865 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.", 866 ) 867 created_by_user: str | None = Field( 868 default=None, 869 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.", 870 ) 871 current_lease: OrgTaskReadyResponseDataItemTaskCurrentLease | None = Field( 872 default=None, 873 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.", 874 ) 875 description: str | None = Field( 876 default=None, 877 description="Long-form description or notes for the task. `null` if no description has been provided.", 878 ) 879 due_date: datetime | None = Field( 880 default=None, 881 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 882 ) 883 epic: str | None = Field( 884 default=None, 885 description="Free-form grouping label. `null` when the task is not in an epic.", 886 ) 887 id: str = Field(..., description="Task ID (`tsk_...`).") 888 is_blocked: bool | None = Field( 889 default=None, 890 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 reads, including mutation responses.", 891 ) 892 is_stalled: bool | None = Field( 893 default=None, 894 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 895 ) 896 links: dict[str, Any] | None = Field( 897 default=None, 898 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 899 ) 900 metadata: dict[str, Any] | None = Field( 901 default=None, 902 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 903 ) 904 name: str = Field(..., description="Human-readable title of the task.") 905 org: str | None = Field( 906 default=None, 907 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 908 ) 909 owner_actor: OrgTaskReadyResponseDataItemTaskOwnerActor | None = Field( 910 default=None, 911 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).", 912 ) 913 owner_agent: str | None = Field( 914 default=None, 915 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.", 916 ) 917 owner_user: str | None = Field( 918 default=None, 919 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.", 920 ) 921 parent: str | None = Field( 922 default=None, 923 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 924 ) 925 priority: int | None = Field( 926 default=None, 927 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 928 ) 929 project_id: str | None = Field( 930 default=None, 931 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 932 ) 933 sandbox: str | None = Field( 934 default=None, 935 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 936 ) 937 source_id: str | None = Field( 938 default=None, 939 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 940 ) 941 source_scope: str | None = Field( 942 default=None, 943 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`.", 944 ) 945 source_type: str | None = Field( 946 default=None, 947 description="Kind of source object (for example `repository`). `null` when the task has no source.", 948 ) 949 stalled_since: datetime | None = Field( 950 default=None, 951 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 952 ) 953 status: str = Field( 954 ..., 955 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 956 ) 957 subtasks_count: int | None = Field( 958 default=None, 959 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 960 ) 961 tags: list[str] | None = Field( 962 default=None, 963 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 964 ) 965 target_binary: str | None = Field( 966 default=None, 967 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 968 ) 969 target_version: str | None = Field( 970 default=None, 971 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 972 ) 973 team: str | None = Field( 974 default=None, 975 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 976 ) 977 thread: str | None = Field( 978 default=None, 979 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.", 980 ) 981 updated_at: datetime | None = Field( 982 default=None, description="When the task was last modified (ISO 8601)." 983 ) 984 user: str | None = Field( 985 default=None, 986 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 987 )
!!! 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.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable 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 reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
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 or when the parent is not readable. 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.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
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.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
OrgTaskReadyResponseDataItem(pydantic.main.BaseModel):
990class OrgTaskReadyResponseDataItem(BaseModel): 991 readiness: Literal["ready", "blocked", "leased"] = Field( 992 ..., description="One of `ready`, `blocked`, or `leased`." 993 ) 994 reason: Literal["open_blockers", "active_lease"] | None = Field( 995 default=None, 996 description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", 997 ) 998 task: OrgTaskReadyResponseDataItemTask = Field( 999 ..., description="The task evaluated for readiness." 1000 )
!!! 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.
readiness: Literal['ready', 'blocked', 'leased'] =
PydanticUndefined
One of ready, blocked, or leased.
class
OrgTaskReadyResponse(pydantic.main.BaseModel):
1003class OrgTaskReadyResponse(BaseModel): 1004 """ 1005 Successful response 1006 """ 1007 1008 after_cursor: str | None = None 1009 authoritative: bool = Field( 1010 ..., 1011 description="Always false because projections can lag writes and a later claim can race this read.", 1012 ) 1013 before_cursor: str | None = None 1014 data: list[OrgTaskReadyResponseDataItem] 1015 has_more: bool
Successful response
class
OrgTaskSearchResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
1018class OrgTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): 1019 file: str | None = Field( 1020 default=None, 1021 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1022 ) 1023 height: int | None = Field( 1024 default=None, description="Height of the image in pixels. `null` if not known." 1025 ) 1026 media: str | None = Field( 1027 default=None, 1028 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1029 ) 1030 mime_type: str | None = Field( 1031 default=None, 1032 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1033 ) 1034 refresh_url: str | None = Field( 1035 default=None, 1036 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.", 1037 ) 1038 url: str | None = Field( 1039 default=None, 1040 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.", 1041 ) 1042 width: int | None = Field( 1043 default=None, description="Width of the image in pixels. `null` if not known." 1044 )
!!! 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
OrgTaskSearchResponseDataItemCreatedByActor(pydantic.main.BaseModel):
1047class OrgTaskSearchResponseDataItemCreatedByActor(BaseModel): 1048 alias: str | None = Field( 1049 default=None, 1050 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1051 ) 1052 id: str | None = Field( 1053 default=None, 1054 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1055 ) 1056 name: str | None = Field( 1057 default=None, 1058 description="Display name of the actor shown in the UI. `null` if no name is set.", 1059 ) 1060 profile_picture: OrgTaskSearchResponseDataItemCreatedByActorProfilePicture | None = Field( 1061 default=None, 1062 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1063 )
!!! 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
OrgTaskSearchResponseDataItemCurrentLease(pydantic.main.BaseModel):
1066class OrgTaskSearchResponseDataItemCurrentLease(BaseModel): 1067 expires_at: datetime = Field( 1068 ..., description="Server-calculated lease expiry in ISO 8601 format." 1069 ) 1070 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 1071 session_name: str = Field( 1072 ..., description="Display name supplied by the coding session that holds the lease." 1073 )
!!! 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
OrgTaskSearchResponseDataItemOwnerActorProfilePicture(pydantic.main.BaseModel):
1076class OrgTaskSearchResponseDataItemOwnerActorProfilePicture(BaseModel): 1077 file: str | None = Field( 1078 default=None, 1079 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1080 ) 1081 height: int | None = Field( 1082 default=None, description="Height of the image in pixels. `null` if not known." 1083 ) 1084 media: str | None = Field( 1085 default=None, 1086 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1087 ) 1088 mime_type: str | None = Field( 1089 default=None, 1090 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1091 ) 1092 refresh_url: str | None = Field( 1093 default=None, 1094 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.", 1095 ) 1096 url: str | None = Field( 1097 default=None, 1098 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.", 1099 ) 1100 width: int | None = Field( 1101 default=None, description="Width of the image in pixels. `null` if not known." 1102 )
!!! 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
OrgTaskSearchResponseDataItemOwnerActor(pydantic.main.BaseModel):
1105class OrgTaskSearchResponseDataItemOwnerActor(BaseModel): 1106 alias: str | None = Field( 1107 default=None, 1108 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1109 ) 1110 id: str | None = Field( 1111 default=None, 1112 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1113 ) 1114 name: str | None = Field( 1115 default=None, 1116 description="Display name of the actor shown in the UI. `null` if no name is set.", 1117 ) 1118 profile_picture: OrgTaskSearchResponseDataItemOwnerActorProfilePicture | None = Field( 1119 default=None, 1120 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1121 )
!!! 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
OrgTaskSearchResponseDataItem(pydantic.main.BaseModel):
1124class OrgTaskSearchResponseDataItem(BaseModel): 1125 agent: str | None = Field( 1126 default=None, 1127 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 1128 ) 1129 aggregate_version: int | None = Field( 1130 default=None, 1131 description="Event-stream version for optimistic update fencing. Pass this value as `expected_version` on an update to reject concurrent writes.", 1132 ) 1133 blocked_by_count: int | None = Field( 1134 default=None, 1135 description="Number of readable 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.", 1136 ) 1137 closed_at: datetime | None = Field( 1138 default=None, 1139 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 1140 ) 1141 comments_count: int | None = Field( 1142 default=None, description="Total number of comments posted on this task." 1143 ) 1144 created_at: datetime | None = Field( 1145 default=None, description="When the task was created (ISO 8601)." 1146 ) 1147 created_by_actor: OrgTaskSearchResponseDataItemCreatedByActor | None = Field( 1148 default=None, 1149 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).", 1150 ) 1151 created_by_agent: str | None = Field( 1152 default=None, 1153 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.", 1154 ) 1155 created_by_user: str | None = Field( 1156 default=None, 1157 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.", 1158 ) 1159 current_lease: OrgTaskSearchResponseDataItemCurrentLease | None = Field( 1160 default=None, 1161 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.", 1162 ) 1163 description: str | None = Field( 1164 default=None, 1165 description="Long-form description or notes for the task. `null` if no description has been provided.", 1166 ) 1167 due_date: datetime | None = Field( 1168 default=None, 1169 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 1170 ) 1171 epic: str | None = Field( 1172 default=None, 1173 description="Free-form grouping label. `null` when the task is not in an epic.", 1174 ) 1175 id: str = Field(..., description="Task ID (`tsk_...`).") 1176 is_blocked: bool | None = Field( 1177 default=None, 1178 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 reads, including mutation responses.", 1179 ) 1180 is_stalled: bool | None = Field( 1181 default=None, 1182 description="True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.", 1183 ) 1184 links: dict[str, Any] | None = Field( 1185 default=None, 1186 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 1187 ) 1188 metadata: dict[str, Any] | None = Field( 1189 default=None, 1190 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 1191 ) 1192 name: str = Field(..., description="Human-readable title of the task.") 1193 org: str | None = Field( 1194 default=None, 1195 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 1196 ) 1197 owner_actor: OrgTaskSearchResponseDataItemOwnerActor | None = Field( 1198 default=None, 1199 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).", 1200 ) 1201 owner_agent: str | None = Field( 1202 default=None, 1203 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.", 1204 ) 1205 owner_user: str | None = Field( 1206 default=None, 1207 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.", 1208 ) 1209 parent: str | None = Field( 1210 default=None, 1211 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks or when the parent is not readable. Subtasks nest exactly one level.", 1212 ) 1213 priority: int | None = Field( 1214 default=None, 1215 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1216 ) 1217 project_id: str | None = Field( 1218 default=None, 1219 description="Optional project ID (`prj_...`). Membership does not change task visibility.", 1220 ) 1221 sandbox: str | None = Field( 1222 default=None, 1223 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1224 ) 1225 source_id: str | None = Field( 1226 default=None, 1227 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1228 ) 1229 source_scope: str | None = Field( 1230 default=None, 1231 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`.", 1232 ) 1233 source_type: str | None = Field( 1234 default=None, 1235 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1236 ) 1237 stalled_since: datetime | None = Field( 1238 default=None, 1239 description="Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.", 1240 ) 1241 status: str = Field( 1242 ..., 1243 description='Current status of the task. One of `"open"`, `"in_progress"`, `"in_review"`, `"paused"`, `"failed"`, `"superseding"`, `"done"`, or `"cancelled"`.', 1244 ) 1245 subtasks_count: int | None = Field( 1246 default=None, 1247 description="Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1248 ) 1249 tags: list[str] | None = Field( 1250 default=None, 1251 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1252 ) 1253 target_binary: str | None = Field( 1254 default=None, 1255 description="Binary that must run this work (for example `my-cli`). A worker should take the task only when its own `target_binary` build is at least `target_version`. `null` when the task has no target. Set together with `target_version`.", 1256 ) 1257 target_version: str | None = Field( 1258 default=None, 1259 description="Minimum semantic version of `target_binary` that can run this work (for example `0.48.9`), in canonical `MAJOR.MINOR.PATCH[-prerelease][+build]` form. `null` when the task has no target.", 1260 ) 1261 team: str | None = Field( 1262 default=None, 1263 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1264 ) 1265 thread: str | None = Field( 1266 default=None, 1267 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.", 1268 ) 1269 updated_at: datetime | None = Field( 1270 default=None, description="When the task was last modified (ISO 8601)." 1271 ) 1272 user: str | None = Field( 1273 default=None, 1274 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1275 )
!!! 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.
aggregate_version: int | None =
None
Event-stream version for optimistic update fencing. Pass this value as expected_version on an update to reject concurrent writes.
blocked_by_count: int | None =
None
Number of readable 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 reads, including mutation responses.
is_stalled: bool | None =
None
True exactly when status is in_progress and the task has no lease or its lease expiry is in the past. Derived at read time from status and lease expiry, including on unannotated reads.
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 or when the parent is not readable. 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.
project_id: str | None =
None
Optional project ID (prj_...). Membership does not change task visibility.
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.
stalled_since: datetime.datetime | None =
None
Lease expiry for a stalled task, or its last update when no lease expiry exists. Null when not stalled.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", "in_review", "paused", "failed", "superseding", "done", or "cancelled".
subtasks_count: int | None =
None
Number of readable subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
target_binary: str | None =
None
Binary that must run this work (for example my-cli). A worker should take the task only when its own target_binary build is at least target_version. null when the task has no target. Set together with target_version.
target_version: str | None =
None
Minimum semantic version of target_binary that can run this work (for example 0.48.9), in canonical MAJOR.MINOR.PATCH[-prerelease][+build] form. null when the task has no target.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
OrgTaskSearchResponse(pydantic.main.BaseModel):
1278class OrgTaskSearchResponse(BaseModel): 1279 """ 1280 Successful response 1281 """ 1282 1283 after_cursor: str | None = None 1284 before_cursor: str | None = None 1285 data: list[OrgTaskSearchResponseDataItem] = Field( 1286 ..., description="Array of task objects matching the query and filters." 1287 ) 1288 has_more: bool 1289 query: str
Successful response
class
OrgThreadListResponseDataItemParentMessageAclAddItem(pydantic.main.BaseModel):
1292class OrgThreadListResponseDataItemParentMessageAclAddItem(BaseModel): 1293 actions: list[str] = Field( 1294 ..., 1295 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1296 ) 1297 principal: str | None = Field( 1298 default=None, 1299 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1300 ) 1301 principal_type: str = Field( 1302 ..., 1303 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1304 )
!!! 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.
actions: list[str] =
PydanticUndefined
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None =
None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
OrgThreadListResponseDataItemParentMessageAclGrantsItem(pydantic.main.BaseModel):
1307class OrgThreadListResponseDataItemParentMessageAclGrantsItem(BaseModel): 1308 actions: list[str] = Field( 1309 ..., 1310 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1311 ) 1312 principal: str | None = Field( 1313 default=None, 1314 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1315 ) 1316 principal_type: str = Field( 1317 ..., 1318 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1319 )
!!! 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.
actions: list[str] =
PydanticUndefined
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None =
None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
OrgThreadListResponseDataItemParentMessageAclRemoveItem(pydantic.main.BaseModel):
1322class OrgThreadListResponseDataItemParentMessageAclRemoveItem(BaseModel): 1323 principal: str | None = Field( 1324 default=None, 1325 description='The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.', 1326 ) 1327 principal_type: str = Field( 1328 ..., 1329 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1330 )
!!! 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.
principal: str | None =
None
The identifier of the principal to remove. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role". Omit when principal_type is "everyone".
class
OrgThreadListResponseDataItemParentMessageAcl(pydantic.main.BaseModel):
1333class OrgThreadListResponseDataItemParentMessageAcl(BaseModel): 1334 add: list[OrgThreadListResponseDataItemParentMessageAclAddItem] | None = Field( 1335 default=None, 1336 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1337 ) 1338 grants: list[OrgThreadListResponseDataItemParentMessageAclGrantsItem] | None = Field( 1339 default=None, 1340 description="Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", 1341 ) 1342 remove: list[OrgThreadListResponseDataItemParentMessageAclRemoveItem] | None = Field( 1343 default=None, 1344 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1345 )
!!! 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.
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
OrgThreadListResponseDataItemParentMessageActorsItemProfilePicture(pydantic.main.BaseModel):
1348class OrgThreadListResponseDataItemParentMessageActorsItemProfilePicture(BaseModel): 1349 file: str | None = Field( 1350 default=None, 1351 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1352 ) 1353 height: int | None = Field( 1354 default=None, description="Height of the image in pixels. `null` if not known." 1355 ) 1356 media: str | None = Field( 1357 default=None, 1358 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1359 ) 1360 mime_type: str | None = Field( 1361 default=None, 1362 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1363 ) 1364 refresh_url: str | None = Field( 1365 default=None, 1366 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.", 1367 ) 1368 url: str | None = Field( 1369 default=None, 1370 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.", 1371 ) 1372 width: int | None = Field( 1373 default=None, description="Width of the image in pixels. `null` if not known." 1374 )
!!! 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
OrgThreadListResponseDataItemParentMessageActorsItem(pydantic.main.BaseModel):
1377class OrgThreadListResponseDataItemParentMessageActorsItem(BaseModel): 1378 alias: str | None = Field( 1379 default=None, 1380 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1381 ) 1382 id: str | None = Field( 1383 default=None, 1384 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1385 ) 1386 name: str | None = Field( 1387 default=None, 1388 description="Display name of the actor shown in the UI. `null` if no name is set.", 1389 ) 1390 profile_picture: OrgThreadListResponseDataItemParentMessageActorsItemProfilePicture | None = ( 1391 Field( 1392 default=None, 1393 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1394 ) 1395 )
!!! 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
OrgThreadListResponseDataItemParentMessageAttachmentsItemImageSource(pydantic.main.BaseModel):
1398class OrgThreadListResponseDataItemParentMessageAttachmentsItemImageSource(BaseModel): 1399 file: str | None = Field( 1400 default=None, 1401 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1402 ) 1403 height: int | None = Field( 1404 default=None, description="Height of the image in pixels. `null` if not known." 1405 ) 1406 media: str | None = Field( 1407 default=None, 1408 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1409 ) 1410 mime_type: str | None = Field( 1411 default=None, 1412 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1413 ) 1414 refresh_url: str | None = Field( 1415 default=None, 1416 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.", 1417 ) 1418 url: str | None = Field( 1419 default=None, 1420 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.", 1421 ) 1422 width: int | None = Field( 1423 default=None, description="Width of the image in pixels. `null` if not known." 1424 )
!!! 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
OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(pydantic.main.BaseModel):
1427class OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(BaseModel): 1428 file: str | None = Field( 1429 default=None, 1430 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1431 ) 1432 height: int | None = Field( 1433 default=None, description="Height of the image in pixels. `null` if not known." 1434 ) 1435 media: str | None = Field( 1436 default=None, 1437 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1438 ) 1439 mime_type: str | None = Field( 1440 default=None, 1441 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1442 ) 1443 refresh_url: str | None = Field( 1444 default=None, 1445 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.", 1446 ) 1447 url: str | None = Field( 1448 default=None, 1449 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.", 1450 ) 1451 width: int | None = Field( 1452 default=None, description="Width of the image in pixels. `null` if not known." 1453 )
!!! 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
OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(pydantic.main.BaseModel):
1456class OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(BaseModel): 1457 byte_size: int | None = Field(default=None, description="Size of the stored bytes.") 1458 content_type: str | None = Field( 1459 default=None, 1460 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 1461 ) 1462 created_at: datetime | None = Field( 1463 default=None, description="When this variant was created (ISO 8601)." 1464 ) 1465 duration_ms: int | None = Field( 1466 default=None, 1467 description="Client-declared video duration in milliseconds; not server-probed.", 1468 ) 1469 file: str | None = Field( 1470 default=None, 1471 description="ID of the underlying storage file that backs this variant (`fil_...`).", 1472 ) 1473 filename: str | None = Field( 1474 default=None, 1475 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 1476 ) 1477 height: int | None = Field( 1478 default=None, description="Height of this variant in pixels. `null` if not recorded." 1479 ) 1480 id: str = Field(..., description="Media variant ID (`mvr_...`).") 1481 image_source: ( 1482 OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | None 1483 ) = Field( 1484 default=None, 1485 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 1486 ) 1487 sha256: str | None = Field(default=None, description="Lowercase SHA-256 of the stored bytes.") 1488 updated_at: datetime | None = Field( 1489 default=None, description="When this variant was last updated (ISO 8601)." 1490 ) 1491 url: str | None = Field( 1492 default=None, 1493 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 1494 ) 1495 url_expires_at: datetime | None = Field( 1496 default=None, description="Expiry of this variant's playable URL." 1497 ) 1498 variant_key: str | None = Field( 1499 default=None, 1500 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 1501 ) 1502 width: int | None = Field( 1503 default=None, description="Width of this variant in pixels. `null` if not recorded." 1504 )
!!! 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.
content_type: str | None =
None
MIME type of this variant's file (e.g., "image/jpeg", "video/mp4"). null if the file is not loaded.
filename: str | None =
None
Original filename of the uploaded file for this variant. null if the file is not loaded.
image_source: OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | None =
None
Resolved image delivery metadata for this variant, including dimensions and CDN URL. null for non-image content types.
url: str | None =
None
Signed download URL for this variant, resolved at request time. null if the file is unavailable.
class
OrgThreadListResponseDataItemParentMessageAttachmentsItem(pydantic.main.BaseModel):
1507class OrgThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): 1508 content_type: str | None = Field( 1509 default=None, 1510 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1511 ) 1512 description: str | None = Field( 1513 default=None, 1514 description="Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types.", 1515 ) 1516 filename: str | None = Field( 1517 default=None, 1518 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1519 ) 1520 height: int | None = Field( 1521 default=None, 1522 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 1523 ) 1524 id: str = Field(..., description="Unique identifier for this attachment within the message.") 1525 image_height: int | None = Field( 1526 default=None, 1527 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1528 ) 1529 image_source: OrgThreadListResponseDataItemParentMessageAttachmentsItemImageSource | None = ( 1530 Field( 1531 default=None, 1532 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 1533 ) 1534 ) 1535 image_url: str | None = Field( 1536 default=None, 1537 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 1538 ) 1539 image_width: int | None = Field( 1540 default=None, 1541 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1542 ) 1543 key: str | None = Field( 1544 default=None, 1545 description='For `structured_data` type, what the data is about as set by the sender (for example `"pr:14963"`), copied from the record so it can be read without `object`. Not unique. `null` when unset and on other types.', 1546 ) 1547 media_type: str | None = Field( 1548 default=None, 1549 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 1550 ) 1551 name: str | None = Field( 1552 default=None, 1553 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 1554 ) 1555 object: dict[str, Any] | None = Field( 1556 default=None, 1557 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. For `structured_data` type, contains the inline `data` and the `schema_url` or `schema_config` naming its JSON Schema. Omitted on other types.", 1558 ) 1559 title: str | None = Field( 1560 default=None, 1561 description="Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types.", 1562 ) 1563 type: str = Field( 1564 ..., 1565 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, `"chart"`, or `"structured_data"`. Determines which additional fields are present.', 1566 ) 1567 url: str | None = Field( 1568 default=None, 1569 description="URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types.", 1570 ) 1571 variants: list[OrgThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None = ( 1572 Field( 1573 default=None, 1574 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 1575 ) 1576 ) 1577 version: int | None = Field( 1578 default=None, 1579 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 1580 ) 1581 width: int | None = Field( 1582 default=None, 1583 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 1584 )
!!! 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.
content_type: str | None =
None
MIME type of the attached file, e.g. "image/png" or "application/pdf". Present on file, artifact, and media types. null otherwise.
description: str | None =
None
Short description. The page meta-description for scraped_link, the artifact description for artifact, and the task description for task types. null on other types.
filename: str | None =
None
Original filename of the attached file, e.g. "report.pdf". Present on file, artifact, and media types. null otherwise.
height: int | None =
None
Height in pixels of the media item. Present on media type only. null otherwise.
image_height: int | None =
None
Height in pixels of the scraped preview image. Present on scraped_link type only. null otherwise.
Image source metadata for inline rendering. Present on file, scraped_link, artifact, and media types when the content is an image. null otherwise.
image_url: str | None =
None
URL of the preview image extracted from the scraped page. Present on scraped_link type only. null otherwise.
image_width: int | None =
None
Width in pixels of the scraped preview image. Present on scraped_link type only. null otherwise.
key: str | None =
None
For structured_data type, what the data is about as set by the sender (for example "pr:14963"), copied from the record so it can be read without object. Not unique. null when unset and on other types.
media_type: str | None =
None
The media category, e.g. "video" or "audio". Present on media type only; omitted otherwise.
object: dict[str, typing.Any] | None =
None
The full embedded object payload. For task type, contains the task record. For action type, contains the action definition. For chart type, contains the chart with its inline spec. For structured_data type, contains the inline data and the schema_url or schema_config naming its JSON Schema. Omitted on other types.
title: str | None =
None
Display title. The page title for scraped_link, the artifact name for artifact, and the task title for task types. null on other types.
type: str =
PydanticUndefined
The attachment type. One of "file", "scraped_link", "artifact", "task", "media", "action", "chart", or "structured_data". Determines which additional fields are present.
url: str | None =
None
URL to access the resource. A signed download URL for file and artifact types; the original URL for scraped_link; a media playback URL for media. null on task and action types.
Array of available encoding variants for the media item (e.g. different resolutions). Present on media type only; omitted otherwise.
class
OrgThreadListResponseDataItemParentMessageContextItem(pydantic.main.BaseModel):
1587class OrgThreadListResponseDataItemParentMessageContextItem(BaseModel): 1588 attributes: dict[str, Any] | None = Field( 1589 default=None, 1590 description="Scalar key-value fields describing the context, such as route, repository, or pull-request number.", 1591 ) 1592 content: str | None = Field( 1593 default=None, 1594 description="Optional context body. The model receives it as escaped XML data, not a system instruction.", 1595 ) 1596 title: str | None = Field( 1597 default=None, description="Optional human-readable label for this context block." 1598 ) 1599 type: str = Field( 1600 ..., 1601 description="Stable context kind. Must start with a lowercase letter and contain only lowercase letters, numbers, dots, dashes, or underscores.", 1602 )
!!! 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.
attributes: dict[str, typing.Any] | None =
None
Scalar key-value fields describing the context, such as route, repository, or pull-request number.
class
OrgThreadListResponseDataItemParentMessageReactionsItem(pydantic.main.BaseModel):
1605class OrgThreadListResponseDataItemParentMessageReactionsItem(BaseModel): 1606 payload: dict[str, Any] | None = Field( 1607 default=None, 1608 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 1609 ) 1610 type: str = Field( 1611 ..., 1612 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 1613 ) 1614 user: str | None = Field( 1615 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 1616 )
!!! 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.
payload: dict[str, typing.Any] | None =
None
Type-specific reaction data. For "emoji_reaction" reactions, contains an emoji key with the Unicode emoji string (e.g., " ").
class
OrgThreadListResponseDataItemParentMessage(pydantic.main.BaseModel):
1619class OrgThreadListResponseDataItemParentMessage(BaseModel): 1620 acl: OrgThreadListResponseDataItemParentMessageAcl | None = Field( 1621 default=None, 1622 description="Access control list for private messages (grants with `read` action). Only returned to resource owners (and privileged/org-admin viewers) via server-side `field_redactions: [acl: :owner]`; `null` for everyone else.", 1623 ) 1624 actors: list[OrgThreadListResponseDataItemParentMessageActorsItem] | None = Field( 1625 default=None, 1626 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 1627 ) 1628 agent: str | None = Field( 1629 default=None, 1630 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 1631 ) 1632 agent_mode: Literal["cli", "embedded"] | None = Field( 1633 default=None, 1634 description="Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path.", 1635 ) 1636 attachments: list[OrgThreadListResponseDataItemParentMessageAttachmentsItem] | None = Field( 1637 default=None, 1638 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 1639 ) 1640 branched_thread: str | None = Field( 1641 default=None, 1642 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 1643 ) 1644 content: str | None = Field( 1645 default=None, 1646 description="Text content of the message. `null` for messages that contain only attachments.", 1647 ) 1648 context: list[OrgThreadListResponseDataItemParentMessageContextItem] | None = Field( 1649 default=None, 1650 description="Immutable structured context captured when the message was posted. Each entry has `type`, optional `title` and `content`, and scalar `attributes`. Always present; defaults to an empty array. Context is delivered to agents as escaped XML data, not as system instructions.", 1651 ) 1652 created_at: str | None = Field( 1653 default=None, description="When the message was posted (ISO 8601)." 1654 ) 1655 has_replies: bool | None = Field( 1656 default=None, 1657 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 1658 ) 1659 id: str = Field(..., description="Message ID (`msg_...`).") 1660 idempotency_key: str | None = Field( 1661 default=None, 1662 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 1663 ) 1664 is_deleted: bool | None = Field( 1665 default=None, 1666 description="Whether this message is a deletion tombstone. `true` only on the `message_updated` broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always `false` for live messages.", 1667 ) 1668 legacy_agent: str | None = Field( 1669 default=None, 1670 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 1671 ) 1672 metadata: dict[str, Any] | None = Field( 1673 default=None, 1674 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 1675 ) 1676 org: str | None = Field( 1677 default=None, description="ID of the organization that owns this message (`org_...`)." 1678 ) 1679 reactions: list[OrgThreadListResponseDataItemParentMessageReactionsItem] | None = Field( 1680 default=None, 1681 description="Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded.", 1682 ) 1683 rendering_mode: str | None = Field( 1684 default=None, 1685 description='Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.', 1686 ) 1687 replies: list[dict[str, Any]] | None = Field( 1688 default=None, 1689 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 1690 ) 1691 replies_after_cursor: str | None = Field( 1692 default=None, 1693 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 1694 ) 1695 replies_before_cursor: str | None = Field( 1696 default=None, 1697 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 1698 ) 1699 reply_count: int | None = Field( 1700 default=None, 1701 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 1702 ) 1703 reply_to: dict[str, Any] | None = Field( 1704 default=None, 1705 description="The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded.", 1706 ) 1707 root_message_id: str | None = Field( 1708 default=None, 1709 description="ID of the root message in this reply chain (`msg_...`). `null` for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages.", 1710 ) 1711 sandbox: str | None = Field( 1712 default=None, 1713 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 1714 ) 1715 team: str | None = Field( 1716 default=None, 1717 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 1718 ) 1719 thread: str | None = Field( 1720 default=None, description="ID of the thread this message belongs to (`thr_...`)." 1721 ) 1722 type: str | None = Field( 1723 default=None, 1724 description="Optional client-defined classification for the message (for example `note` or `status`). Free-form string up to 64 characters. The value `system` is reserved for platform-authored messages and cannot be set by clients. `null` when unset.", 1725 ) 1726 user: str | dict[str, Any] | None = Field( 1727 default=None, 1728 description="The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents.", 1729 ) 1730 visibility: Literal["default", "private"] | None = Field( 1731 default=None, 1732 description="Message-level visibility. `default` is visible to anyone who can see the parent thread. `private` is restricted to the sender and explicit ACL `read` grantees.", 1733 )
!!! 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.
Access control list for private messages (grants with read action). Only returned to resource owners (and privileged/org-admin viewers) via server-side field_redactions: [acl: :owner]; null for everyone else.
Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.
agent: str | None =
None
ID of the agent user that sent this message (agi_...). null for messages sent by human users.
agent_mode: Optional[Literal['cli', 'embedded']] =
None
Local agent execution mode for this message. One of cli, embedded, or null when the message was not created by a local agent execution path.
Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.
branched_thread: str | None =
None
ID of the thread that was branched from this message (thr_...). null if this message has not spawned a branch thread.
content: str | None =
None
Text content of the message. null for messages that contain only attachments.
has_replies: bool | None =
None
Whether this message has at least one reply. Only present when explicitly requested or computed by the server.
idempotency_key: str | None =
None
Client-supplied idempotency key used to deduplicate message sends. null if the sender did not provide one.
is_deleted: bool | None =
None
Whether this message is a deletion tombstone. true only on the message_updated broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always false for live messages.
legacy_agent: str | None =
None
Identifier of the legacy chat agent that sent this message, if applicable. null for messages sent by users or modern agent users.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.
Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded.
rendering_mode: str | None =
None
Display hint for how the message should be rendered. One of "reply", "direct", or "inline". null for user-authored messages, which are always rendered as standard replies.
replies: list[dict[str, typing.Any]] | None =
None
Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.
replies_after_cursor: str | None =
None
Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.
replies_before_cursor: str | None =
None
Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.
reply_count: int | None =
None
Total number of direct replies to this message. Only present when explicitly requested or computed by the server.
reply_to: dict[str, typing.Any] | None =
None
The parent message this message is a reply to, expanded as a full message object when loaded. null if this is a top-level message or the association is not preloaded.
root_message_id: str | None =
None
ID of the root message in this reply chain (msg_...). null for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages.
sandbox: str | None =
None
ID of the developer sandbox this message belongs to (dsb_...). null for non-sandbox messages.
team: str | None =
None
ID of the team this message is scoped to (tem_...). null if the message is not team-scoped.
type: str | None =
None
Optional client-defined classification for the message (for example note or status). Free-form string up to 64 characters. The value system is reserved for platform-authored messages and cannot be set by clients. null when unset.
class
OrgThreadListResponseDataItemParticipantsItem(pydantic.main.BaseModel):
1736class OrgThreadListResponseDataItemParticipantsItem(BaseModel): 1737 alias: str | None = Field( 1738 default=None, description="Short handle or alias for the user. `null` if not set." 1739 ) 1740 app: str | None = Field( 1741 default=None, 1742 description="ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.", 1743 ) 1744 app_name: str | None = Field( 1745 default=None, 1746 description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", 1747 ) 1748 created_by_agent_user: str | None = Field( 1749 default=None, 1750 description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", 1751 ) 1752 created_by_developer: str | None = Field( 1753 default=None, 1754 description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", 1755 ) 1756 created_by_org: str | None = Field( 1757 default=None, 1758 description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", 1759 ) 1760 created_by_team: str | None = Field( 1761 default=None, 1762 description="Team that created this user (`tem_...`). `null` unless created as a team.", 1763 ) 1764 created_by_user: str | None = Field( 1765 default=None, 1766 description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", 1767 ) 1768 email: str | None = Field(default=None, description="Email address of the user.") 1769 id: str = Field(..., description="User ID (`usr_...`).") 1770 is_system_user: bool | None = Field( 1771 default=None, 1772 description="`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", 1773 ) 1774 metadata: dict[str, Any] | None = Field( 1775 default=None, 1776 description="Arbitrary key-value metadata attached to the user. Defaults to an empty object.", 1777 ) 1778 name: str | None = Field( 1779 default=None, 1780 description="Full display name of the user. `null` if the user has not set a name.", 1781 ) 1782 org: str | None = Field( 1783 default=None, 1784 description="ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", 1785 ) 1786 org_name: str | None = Field( 1787 default=None, 1788 description="Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.", 1789 ) 1790 org_role: str | None = Field( 1791 default=None, 1792 description='Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.', 1793 ) 1794 org_slug: str | None = Field( 1795 default=None, 1796 description="Stable workspace slug for the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.", 1797 ) 1798 sandbox: str | None = Field( 1799 default=None, 1800 description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", 1801 ) 1802 sandbox_name: str | None = Field( 1803 default=None, 1804 description="Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", 1805 )
!!! 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.
app: str | None =
None
ID of the app this user (and their access token) is scoped to (dap_...). null if the user is not scoped to an app.
app_name: str | None =
None
Display name of the user's app. null when the app association was not preloaded by the caller.
created_by_agent_user: str | None =
None
Agent user that created this account (usr_...). null unless an agent created it.
created_by_developer: str | None =
None
Developer account that created this user (dva_...). null unless created via a developer token.
created_by_org: str | None =
None
Org of the principal that created this user (org_...). null on legacy rows.
created_by_team: str | None =
None
Team that created this user (tem_...). null unless created as a team.
created_by_user: str | None =
None
User who created this account (usr_...). null on self-signup or legacy rows.
is_system_user: bool | None =
None
true if this account is an internal system user rather than a human. System users are created automatically by the platform.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the user. Defaults to an empty object.
org: str | None =
None
ID of the organization this user belongs to (org_...). null if the user is not a member of any organization.
org_name: str | None =
None
Display name of the user's organization. null when the user is not in an org, or when the org association was not preloaded by the caller.
org_role: str | None =
None
Role of the user within their organization. One of "admin", "member", or "viewer". null when the user is not a member of any organization.
org_slug: str | None =
None
Stable workspace slug for the user's organization. null when the user is not in an org, or when the org association was not preloaded by the caller.
class
OrgThreadListResponseDataItemParticipatingAgentsItemAclAddItem(pydantic.main.BaseModel):
1808class OrgThreadListResponseDataItemParticipatingAgentsItemAclAddItem(BaseModel): 1809 actions: list[str] = Field( 1810 ..., 1811 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1812 ) 1813 principal: str | None = Field( 1814 default=None, 1815 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1816 ) 1817 principal_type: str = Field( 1818 ..., 1819 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1820 )
!!! 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.
actions: list[str] =
PydanticUndefined
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None =
None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
OrgThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(pydantic.main.BaseModel):
1823class OrgThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(BaseModel): 1824 actions: list[str] = Field( 1825 ..., 1826 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1827 ) 1828 principal: str | None = Field( 1829 default=None, 1830 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 1831 ) 1832 principal_type: str = Field( 1833 ..., 1834 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1835 )
!!! 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.
actions: list[str] =
PydanticUndefined
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None =
None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
OrgThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(pydantic.main.BaseModel):
1838class OrgThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(BaseModel): 1839 principal: str | None = Field( 1840 default=None, 1841 description='The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.', 1842 ) 1843 principal_type: str = Field( 1844 ..., 1845 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1846 )
!!! 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.
principal: str | None =
None
The identifier of the principal to remove. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role". Omit when principal_type is "everyone".
class
OrgThreadListResponseDataItemParticipatingAgentsItemAcl(pydantic.main.BaseModel):
1849class OrgThreadListResponseDataItemParticipatingAgentsItemAcl(BaseModel): 1850 add: list[OrgThreadListResponseDataItemParticipatingAgentsItemAclAddItem] | None = Field( 1851 default=None, 1852 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1853 ) 1854 grants: list[OrgThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem] | None = Field( 1855 default=None, 1856 description="Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", 1857 ) 1858 remove: list[OrgThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem] | None = Field( 1859 default=None, 1860 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1861 )
!!! 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.
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo(pydantic.main.BaseModel):
1864class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo( 1865 BaseModel 1866): 1867 file: str | None = Field( 1868 default=None, 1869 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1870 ) 1871 height: int | None = Field( 1872 default=None, description="Height of the image in pixels. `null` if not known." 1873 ) 1874 media: str | None = Field( 1875 default=None, 1876 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1877 ) 1878 mime_type: str | None = Field( 1879 default=None, 1880 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1881 ) 1882 refresh_url: str | None = Field( 1883 default=None, 1884 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.", 1885 ) 1886 url: str | None = Field( 1887 default=None, 1888 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.", 1889 ) 1890 width: int | None = Field( 1891 default=None, description="Width of the image in pixels. `null` if not known." 1892 )
!!! 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
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem(pydantic.main.BaseModel):
1895class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 1896 BaseModel 1897): 1898 description: str | None = Field( 1899 default=None, 1900 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 1901 ) 1902 name: str = Field( 1903 ..., 1904 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 1905 ) 1906 required: bool = Field( 1907 ..., 1908 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 1909 ) 1910 type: str = Field( 1911 ..., 1912 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 1913 )
!!! 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.
description: str | None =
None
Workflow-authored explanation of the slot's role. null when the workflow declares none.
name: str =
PydanticUndefined
The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level participants[name] field when invoking.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills(pydantic.main.BaseModel):
1916class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills( 1917 BaseModel 1918): 1919 participants: dict[str, Any] | None = Field( 1920 default=None, 1921 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 1922 ) 1923 payload: dict[str, Any] | None = Field( 1924 default=None, 1925 description="Partial invocation payload applied by the platform. A caller may omit these values, but supplying a different value at any locked path is rejected.", 1926 )
!!! 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
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract(pydantic.main.BaseModel):
1929class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract( 1930 BaseModel 1931): 1932 input_schema: dict[str, Any] | None = Field( 1933 default=None, 1934 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 1935 ) 1936 participants: ( 1937 list[ 1938 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem 1939 ] 1940 | None 1941 ) = Field( 1942 default=None, 1943 description="Named participant slots declared by the workflow, sorted by name. `null` when the workflow declares none. Values supplied under the top-level `participants` field are agent IDs.", 1944 ) 1945 prefills: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 1946 ..., 1947 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 1948 )
!!! 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.
input_schema: dict[str, typing.Any] | None =
None
JSON Schema validated against the whole invoke payload, from the automation's input_schema_config. null when none is configured.
participants: list[OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem] | None =
None
Named participant slots declared by the workflow, sorted by name. null when the workflow declares none. Values supplied under the top-level participants field are agent IDs.
prefills: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills =
PydanticUndefined
Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails(pydantic.main.BaseModel):
1951class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails( 1952 BaseModel 1953): 1954 automation_type: str | None = Field( 1955 default=None, 1956 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 1957 ) 1958 invoke_contract: ( 1959 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract 1960 | None 1961 ) = Field( 1962 default=None, 1963 description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. `null` for non-invoked automation types.", 1964 ) 1965 type: Literal["automation"] = Field( 1966 default="automation", 1967 description="Template-details discriminator. Always `automation` for this variant.", 1968 )
!!! 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.
automation_type: str | None =
None
Automation execution type (invoked, scheduled, or trigger). null when the template body does not declare one.
invoke_contract: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract | None =
None
Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. null for non-invoked automation types.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem(pydantic.main.BaseModel):
1971class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem( 1972 BaseModel 1973): 1974 description: str | None = Field( 1975 default=None, 1976 description="Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.", 1977 ) 1978 details: ( 1979 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails 1980 | None 1981 ) = Field( 1982 default=None, 1983 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 1984 ) 1985 display_name: str | None = Field( 1986 default=None, 1987 description="Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.", 1988 ) 1989 id: str | None = Field( 1990 default=None, 1991 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 1992 ) 1993 kind: str = Field( 1994 ..., 1995 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 1996 ) 1997 lookup_key: str | None = Field( 1998 default=None, 1999 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2000 ) 2001 name: str | None = Field( 2002 default=None, 2003 description="Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.", 2004 ) 2005 readme_url: str | None = Field( 2006 default=None, 2007 description="Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2008 ) 2009 virtual_path: str | None = Field( 2010 default=None, 2011 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2012 )
!!! 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.
description: str | None =
None
Short prose blurb from the template body's description: field. null when the body doesn't set one. Used as the card subhead in the Library carousel.
details: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails | None =
None
Template-kind-specific details selected by the type discriminator. null when this template kind has no additional details.
display_name: str | None =
None
Human-facing label from the template body's display_name: field. null when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized name.
kind: str =
PydanticUndefined
Template config kind, or SolutionTemplateRef / SolutionTemplatePath when unresolved.
lookup_key: str | None =
None
Lookup key stamped on the template config at import time. null when no lookup key was assigned.
name: str | None =
None
Canonical name from the template body. For AgentTemplate this doubles as the human-facing label; for AgentToolTemplate it's the LLM-facing tool function identifier (snake_case); for AgentRoutineTemplate it's the routine identifier (kebab-case). Clients rendering carousels should prefer display_name and fall back to humanizing name.
readme_url: str | None =
None
Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. null when the Solution body's templates[].readme_path is unset for this entry. Token expires in 1 hour refresh via GET /api/v1/solutions/:solution.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(pydantic.main.BaseModel):
2015class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(BaseModel): 2016 category_keys: list[str] | None = Field( 2017 default=None, 2018 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2019 ) 2020 created_at: str | None = Field( 2021 default=None, description="When the Solution config was first imported (ISO 8601)." 2022 ) 2023 description: str | None = Field( 2024 default=None, 2025 description="Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.", 2026 ) 2027 events: dict[str, Any] | None = Field( 2028 default=None, 2029 description="Custom analytics events declared in the Solution body's `events:` manifest a map of event key (snake_case) to its definition (`label`, optional `description`, optional typed `fields`). Dashboards use the `label` as the event's display name. Present as an empty object when the body declares none.", 2030 ) 2031 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2032 image_url: str | None = Field( 2033 default=None, 2034 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2035 ) 2036 installed_config_ids: list[str] = Field( 2037 ..., 2038 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2039 ) 2040 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2041 latest_solution: str | None = Field( 2042 default=None, 2043 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2044 ) 2045 latest_version: str | None = Field( 2046 default=None, 2047 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2048 ) 2049 lookup_key: str | None = Field( 2050 default=None, 2051 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2052 ) 2053 metadata: dict[str, Any] | None = Field( 2054 default=None, 2055 description="Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.", 2056 ) 2057 name: str | None = Field( 2058 default=None, 2059 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2060 ) 2061 org: str | None = Field( 2062 default=None, 2063 description="Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.", 2064 ) 2065 org_logo: ( 2066 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo 2067 | None 2068 ) = Field( 2069 default=None, 2070 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. The `url` is a stable, non-expiring capability URL (`refresh_url` is `null` there is nothing to refresh). `null` when `org_slug` is `null` or the org has no logo.", 2071 ) 2072 org_name: str | None = Field( 2073 default=None, 2074 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2075 ) 2076 org_slug: str | None = Field( 2077 default=None, 2078 description="Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.", 2079 ) 2080 owners: list[str] = Field( 2081 ..., 2082 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2083 ) 2084 readme_url: str | None = Field( 2085 default=None, 2086 description="Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2087 ) 2088 screenshot_urls: list[str] | None = Field( 2089 default=None, 2090 description="Absolute URLs of the Solution's gallery screenshots the bundled assets the body's `screenshots:` field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as `image_url` (one shared token, a `v` cache key, and a `file` param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.", 2091 ) 2092 solution_id: str | None = Field( 2093 default=None, 2094 description="Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.", 2095 ) 2096 solution_version: str | None = Field( 2097 default=None, 2098 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2099 ) 2100 tag_keys: list[str] | None = Field( 2101 default=None, 2102 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2103 ) 2104 template_kind: str | None = Field( 2105 default=None, 2106 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2107 ) 2108 templates: list[ 2109 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem 2110 ] = Field( 2111 ..., 2112 description="Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.", 2113 ) 2114 updated_at: str | None = Field( 2115 default=None, description="When the Solution config was last modified (ISO 8601)." 2116 ) 2117 upgrade_available: bool = Field( 2118 ..., 2119 description="`true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.", 2120 ) 2121 virtual_path: str | None = Field( 2122 default=None, 2123 description="The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.", 2124 )
!!! 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.
category_keys: list[str] | None =
None
Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
description: str | None =
None
Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. null when the Solution body does not set one.
events: dict[str, typing.Any] | None =
None
Custom analytics events declared in the Solution body's events: manifest a map of event key (snake_case) to its definition (label, optional description, optional typed fields). Dashboards use the label as the event's display name. Present as an empty object when the body declares none.
image_url: str | None =
None
Absolute URL of the Solution's cover image the bundled asset the body's image: field names. A stable, non-expiring capability URL (like org_logo.url), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. null when the Solution has no cover image. Org-only rows remain null; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.
installed_config_ids: list[str] =
PydanticUndefined
Config IDs (cfg_...) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.
latest_solution: str | None =
None
When upgrade_available is true, the system-scope Solution config ID (cfg_...) that should be used as the upgrade source. null otherwise.
latest_version: str | None =
None
When upgrade_available is true, the higher system-scope solution_version available to upgrade to. null otherwise.
lookup_key: str | None =
None
The lookup key stored on the Solution config, if one was assigned during import. null when no lookup key was set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
name: str | None =
None
Human-facing display name declared in the Solution body. null when the Solution body does not set one.
org: str | None =
None
Organization ID (org_...) that owns this Solution config, when the Solution is scoped to a specific org. null for system-scope (app-level) Solutions.
org_logo: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo | None =
None
org_slug: str | None =
None
Resolved slug of the Solution body's org (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of category_keys. null when the body has no org or it doesn't resolve.
owners: list[str] =
PydanticUndefined
Owner scopes this Solution appears under. Members: "system" (app-level system scope) and/or "org" (viewer's org scope).
readme_url: str | None =
None
Relative path to the public README endpoint with a signed token already embedded. null when the Solution has no README. Token expires in 1 hour refresh via GET /api/v1/solutions/:solution.
screenshot_urls: list[str] | None =
None
Absolute URLs of the Solution's gallery screenshots the bundled assets the body's screenshots: field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as image_url (one shared token, a v cache key, and a file param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.
solution_id: str | None =
None
Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. null when the body omits it.
solution_version: str | None =
None
Semver string declared in the Solution body (e.g. "1.2.0"). null when the body does not declare a version.
tag_keys: list[str] | None =
None
Freeform tag keys declared in the Solution body. An empty array when the body declares none.
template_kind: str | None =
None
Wrapped template kind "AgentTemplate", "AutomationTemplate", "AgentRoutineTemplate", "AgentToolTemplate", "AgentComputerTemplate", or "SolutionTemplateRef" for ref-mode bundles.
templates: list[OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem] =
PydanticUndefined
Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.
upgrade_available: bool =
PydanticUndefined
true when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher solution_version. Always false for system-only rows.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(pydantic.main.BaseModel):
2127class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(BaseModel): 2128 file: str | None = Field( 2129 default=None, 2130 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2131 ) 2132 height: int | None = Field( 2133 default=None, description="Height of the image in pixels. `null` if not known." 2134 ) 2135 media: str | None = Field( 2136 default=None, 2137 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2138 ) 2139 mime_type: str | None = Field( 2140 default=None, 2141 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2142 ) 2143 refresh_url: str | None = Field( 2144 default=None, 2145 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.", 2146 ) 2147 url: str | None = Field( 2148 default=None, 2149 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.", 2150 ) 2151 width: int | None = Field( 2152 default=None, description="Width of the image in pixels. `null` if not known." 2153 )
!!! 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
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem(pydantic.main.BaseModel):
2156class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 2157 BaseModel 2158): 2159 description: str | None = Field( 2160 default=None, 2161 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 2162 ) 2163 name: str = Field( 2164 ..., 2165 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 2166 ) 2167 required: bool = Field( 2168 ..., 2169 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2170 ) 2171 type: str = Field( 2172 ..., 2173 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2174 )
!!! 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.
description: str | None =
None
Workflow-authored explanation of the slot's role. null when the workflow declares none.
name: str =
PydanticUndefined
The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level participants[name] field when invoking.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills(pydantic.main.BaseModel):
2177class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills( 2178 BaseModel 2179): 2180 participants: dict[str, Any] | None = Field( 2181 default=None, 2182 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2183 ) 2184 payload: dict[str, Any] | None = Field( 2185 default=None, 2186 description="Partial invocation payload applied by the platform. A caller may omit these values, but supplying a different value at any locked path is rejected.", 2187 )
!!! 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
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract(pydantic.main.BaseModel):
2190class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract( 2191 BaseModel 2192): 2193 input_schema: dict[str, Any] | None = Field( 2194 default=None, 2195 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2196 ) 2197 participants: ( 2198 list[ 2199 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2200 ] 2201 | None 2202 ) = Field( 2203 default=None, 2204 description="Named participant slots declared by the workflow, sorted by name. `null` when the workflow declares none. Values supplied under the top-level `participants` field are agent IDs.", 2205 ) 2206 prefills: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2207 ..., 2208 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2209 )
!!! 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.
input_schema: dict[str, typing.Any] | None =
None
JSON Schema validated against the whole invoke payload, from the automation's input_schema_config. null when none is configured.
participants: list[OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem] | None =
None
Named participant slots declared by the workflow, sorted by name. null when the workflow declares none. Values supplied under the top-level participants field are agent IDs.
prefills: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills =
PydanticUndefined
Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails(pydantic.main.BaseModel):
2212class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails( 2213 BaseModel 2214): 2215 automation_type: str | None = Field( 2216 default=None, 2217 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2218 ) 2219 invoke_contract: ( 2220 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract 2221 | None 2222 ) = Field( 2223 default=None, 2224 description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. `null` for non-invoked automation types.", 2225 ) 2226 type: Literal["automation"] = Field( 2227 default="automation", 2228 description="Template-details discriminator. Always `automation` for this variant.", 2229 )
!!! 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.
automation_type: str | None =
None
Automation execution type (invoked, scheduled, or trigger). null when the template body does not declare one.
invoke_contract: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract | None =
None
Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. null for non-invoked automation types.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem(pydantic.main.BaseModel):
2232class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem( 2233 BaseModel 2234): 2235 description: str | None = Field( 2236 default=None, 2237 description="Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.", 2238 ) 2239 details: ( 2240 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails 2241 | None 2242 ) = Field( 2243 default=None, 2244 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2245 ) 2246 display_name: str | None = Field( 2247 default=None, 2248 description="Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.", 2249 ) 2250 id: str | None = Field( 2251 default=None, 2252 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2253 ) 2254 kind: str = Field( 2255 ..., 2256 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2257 ) 2258 lookup_key: str | None = Field( 2259 default=None, 2260 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2261 ) 2262 name: str | None = Field( 2263 default=None, 2264 description="Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.", 2265 ) 2266 readme_url: str | None = Field( 2267 default=None, 2268 description="Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2269 ) 2270 virtual_path: str | None = Field( 2271 default=None, 2272 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2273 )
!!! 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.
description: str | None =
None
Short prose blurb from the template body's description: field. null when the body doesn't set one. Used as the card subhead in the Library carousel.
details: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails | None =
None
Template-kind-specific details selected by the type discriminator. null when this template kind has no additional details.
display_name: str | None =
None
Human-facing label from the template body's display_name: field. null when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized name.
kind: str =
PydanticUndefined
Template config kind, or SolutionTemplateRef / SolutionTemplatePath when unresolved.
lookup_key: str | None =
None
Lookup key stamped on the template config at import time. null when no lookup key was assigned.
name: str | None =
None
Canonical name from the template body. For AgentTemplate this doubles as the human-facing label; for AgentToolTemplate it's the LLM-facing tool function identifier (snake_case); for AgentRoutineTemplate it's the routine identifier (kebab-case). Clients rendering carousels should prefer display_name and fall back to humanizing name.
readme_url: str | None =
None
Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. null when the Solution body's templates[].readme_path is unset for this entry. Token expires in 1 hour refresh via GET /api/v1/solutions/:solution.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(pydantic.main.BaseModel):
2276class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(BaseModel): 2277 category_keys: list[str] | None = Field( 2278 default=None, 2279 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2280 ) 2281 created_at: str | None = Field( 2282 default=None, description="When the Solution config was first imported (ISO 8601)." 2283 ) 2284 description: str | None = Field( 2285 default=None, 2286 description="Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.", 2287 ) 2288 events: dict[str, Any] | None = Field( 2289 default=None, 2290 description="Custom analytics events declared in the Solution body's `events:` manifest a map of event key (snake_case) to its definition (`label`, optional `description`, optional typed `fields`). Dashboards use the `label` as the event's display name. Present as an empty object when the body declares none.", 2291 ) 2292 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2293 image_url: str | None = Field( 2294 default=None, 2295 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image. Org-only rows remain `null`; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.", 2296 ) 2297 installed_config_ids: list[str] = Field( 2298 ..., 2299 description="Config IDs (`cfg_...`) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.", 2300 ) 2301 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2302 latest_solution: str | None = Field( 2303 default=None, 2304 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2305 ) 2306 latest_version: str | None = Field( 2307 default=None, 2308 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2309 ) 2310 lookup_key: str | None = Field( 2311 default=None, 2312 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2313 ) 2314 metadata: dict[str, Any] | None = Field( 2315 default=None, 2316 description="Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.", 2317 ) 2318 name: str | None = Field( 2319 default=None, 2320 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2321 ) 2322 org: str | None = Field( 2323 default=None, 2324 description="Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.", 2325 ) 2326 org_logo: ( 2327 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | None 2328 ) = Field( 2329 default=None, 2330 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. The `url` is a stable, non-expiring capability URL (`refresh_url` is `null` there is nothing to refresh). `null` when `org_slug` is `null` or the org has no logo.", 2331 ) 2332 org_name: str | None = Field( 2333 default=None, 2334 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2335 ) 2336 org_slug: str | None = Field( 2337 default=None, 2338 description="Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.", 2339 ) 2340 owners: list[str] = Field( 2341 ..., 2342 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2343 ) 2344 readme_url: str | None = Field( 2345 default=None, 2346 description="Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 2347 ) 2348 screenshot_urls: list[str] | None = Field( 2349 default=None, 2350 description="Absolute URLs of the Solution's gallery screenshots the bundled assets the body's `screenshots:` field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as `image_url` (one shared token, a `v` cache key, and a `file` param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.", 2351 ) 2352 solution_id: str | None = Field( 2353 default=None, 2354 description="Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.", 2355 ) 2356 solution_version: str | None = Field( 2357 default=None, 2358 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2359 ) 2360 tag_keys: list[str] | None = Field( 2361 default=None, 2362 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2363 ) 2364 template_kind: str | None = Field( 2365 default=None, 2366 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2367 ) 2368 templates: list[ 2369 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem 2370 ] = Field( 2371 ..., 2372 description="Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.", 2373 ) 2374 updated_at: str | None = Field( 2375 default=None, description="When the Solution config was last modified (ISO 8601)." 2376 ) 2377 upgrade_available: bool = Field( 2378 ..., 2379 description="`true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.", 2380 ) 2381 virtual_path: str | None = Field( 2382 default=None, 2383 description="The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.", 2384 )
!!! 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.
category_keys: list[str] | None =
None
Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
description: str | None =
None
Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. null when the Solution body does not set one.
events: dict[str, typing.Any] | None =
None
Custom analytics events declared in the Solution body's events: manifest a map of event key (snake_case) to its definition (label, optional description, optional typed fields). Dashboards use the label as the event's display name. Present as an empty object when the body declares none.
image_url: str | None =
None
Absolute URL of the Solution's cover image the bundled asset the body's image: field names. A stable, non-expiring capability URL (like org_logo.url), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. null when the Solution has no cover image. Org-only rows remain null; when a list entry merges an org copy with its system counterpart, it may reuse the system row's public cover URL. Permanent URLs are never minted for private org assets.
installed_config_ids: list[str] =
PydanticUndefined
Config IDs (cfg_...) of this Solution's installations in the viewer's organization. The array is empty when the Solution is visible only from the system catalog.
latest_solution: str | None =
None
When upgrade_available is true, the system-scope Solution config ID (cfg_...) that should be used as the upgrade source. null otherwise.
latest_version: str | None =
None
When upgrade_available is true, the higher system-scope solution_version available to upgrade to. null otherwise.
lookup_key: str | None =
None
The lookup key stored on the Solution config, if one was assigned during import. null when no lookup key was set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
name: str | None =
None
Human-facing display name declared in the Solution body. null when the Solution body does not set one.
org: str | None =
None
Organization ID (org_...) that owns this Solution config, when the Solution is scoped to a specific org. null for system-scope (app-level) Solutions.
org_logo: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | None =
None
org_slug: str | None =
None
Resolved slug of the Solution body's org (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of category_keys. null when the body has no org or it doesn't resolve.
owners: list[str] =
PydanticUndefined
Owner scopes this Solution appears under. Members: "system" (app-level system scope) and/or "org" (viewer's org scope).
readme_url: str | None =
None
Relative path to the public README endpoint with a signed token already embedded. null when the Solution has no README. Token expires in 1 hour refresh via GET /api/v1/solutions/:solution.
screenshot_urls: list[str] | None =
None
Absolute URLs of the Solution's gallery screenshots the bundled assets the body's screenshots: field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as image_url (one shared token, a v cache key, and a file param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.
solution_id: str | None =
None
Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. null when the body omits it.
solution_version: str | None =
None
Semver string declared in the Solution body (e.g. "1.2.0"). null when the body does not declare a version.
tag_keys: list[str] | None =
None
Freeform tag keys declared in the Solution body. An empty array when the body declares none.
template_kind: str | None =
None
Wrapped template kind "AgentTemplate", "AutomationTemplate", "AgentRoutineTemplate", "AgentToolTemplate", "AgentComputerTemplate", or "SolutionTemplateRef" for ref-mode bundles.
templates: list[OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem] =
PydanticUndefined
Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.
upgrade_available: bool =
PydanticUndefined
true when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher solution_version. Always false for system-only rows.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(pydantic.main.BaseModel):
2387class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(BaseModel): 2388 created_at: datetime | None = Field( 2389 default=None, description="When this template config was created (ISO 8601)." 2390 ) 2391 description: str | None = Field( 2392 default=None, 2393 description="Description of the template from the config body. `null` if the current version has no `description` field.", 2394 ) 2395 display_name: str | None = Field( 2396 default=None, 2397 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 2398 ) 2399 id: str = Field(..., description="Template config ID (`cfg_...`).") 2400 kind: str = Field( 2401 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 2402 ) 2403 lookup_key: str | None = Field( 2404 default=None, 2405 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 2406 ) 2407 name: str | None = Field( 2408 default=None, 2409 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 2410 ) 2411 updated_at: datetime | None = Field( 2412 default=None, description="When this template config was last modified (ISO 8601)." 2413 ) 2414 virtual_path: str | None = Field( 2415 default=None, 2416 description="Virtual filesystem path for this template config. `null` if not set.", 2417 )
!!! 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.
description: str | None =
None
Description of the template from the config body. null if the current version has no description field.
display_name: str | None =
None
Human-readable display name from the config body. null if the current version has no display_name field.
kind: str =
PydanticUndefined
Config kind identifier for this template (e.g. "agent_tool_template").
lookup_key: str | None =
None
Stable lookup key assigned to this template config. null if no lookup key is set.
name: str | None =
None
Template name as stored in the config body. null if the current version has no name field.
class
OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolution(pydantic.main.BaseModel):
2420class OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolution(BaseModel): 2421 current_solution: ( 2422 OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | None 2423 ) = Field( 2424 default=None, 2425 description="Summary of the current parent Solution config row. `solution` is the pinned Solution version the agent points at; `current_solution` is the source Solution config row as it exists now.", 2426 ) 2427 solution: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution = Field( 2428 ..., 2429 description="Summary of the parent Solution, including `upgrade_available`, `latest_version`, and `latest_solution` when a newer system-scoped version is available for the agent's org-scoped Solution.", 2430 ) 2431 template: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate = Field( 2432 ..., 2433 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2434 )
!!! 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.
current_solution: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | None =
None
Summary of the current parent Solution config row. solution is the pinned Solution version the agent points at; current_solution is the source Solution config row as it exists now.
solution: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution =
PydanticUndefined
Summary of the parent Solution, including upgrade_available, latest_version, and latest_solution when a newer system-scoped version is available for the agent's org-scoped Solution.
template: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate =
PydanticUndefined
Summary of the AgentTemplate config (cfg_...) the agent was last provisioned or updated from.
class
OrgThreadListResponseDataItemParticipatingAgentsItem(pydantic.main.BaseModel):
2437class OrgThreadListResponseDataItemParticipatingAgentsItem(BaseModel): 2438 acl: OrgThreadListResponseDataItemParticipatingAgentsItemAcl | None = Field( 2439 default=None, 2440 description="Access control list for the agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the agent is accessible to all members of its scope.", 2441 ) 2442 app: str | None = Field( 2443 default=None, description="ID of the application that owns this agent (`dap_...`)." 2444 ) 2445 created_at: str | None = Field( 2446 default=None, description="When the agent was created (ISO 8601)." 2447 ) 2448 default_model: str | None = Field( 2449 default=None, 2450 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2451 ) 2452 description: str | None = Field( 2453 default=None, 2454 description="Human-readable description of what the agent does. `null` if not set.", 2455 ) 2456 email: str | None = Field( 2457 default=None, 2458 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2459 ) 2460 id: str = Field(..., description="Agent ID (`agi_...`).") 2461 identity: str | None = Field( 2462 default=None, 2463 description="System-level identity prompt that shapes the agent's persona and behavior.", 2464 ) 2465 last_applied_template_config: str | None = Field( 2466 default=None, 2467 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2468 ) 2469 lookup_key: str | None = Field( 2470 default=None, 2471 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2472 ) 2473 metadata: dict[str, Any] | None = Field( 2474 default=None, 2475 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2476 ) 2477 name: str | None = Field( 2478 default=None, description="Human-readable display name for the agent. `null` if not set." 2479 ) 2480 org: str | None = Field( 2481 default=None, 2482 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2483 ) 2484 org_name: str | None = Field( 2485 default=None, 2486 description="Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded.", 2487 ) 2488 originator: str | None = Field( 2489 default=None, 2490 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2491 ) 2492 phone_number: str | None = Field( 2493 default=None, 2494 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2495 ) 2496 sandbox: str | None = Field( 2497 default=None, 2498 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2499 ) 2500 source_solution: OrgThreadListResponseDataItemParticipatingAgentsItemSourceSolution | None = ( 2501 Field( 2502 default=None, 2503 description="Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes `upgrade_available`, `latest_version`, and `latest_solution` so you can render an upgrade badge without a separate dry-run call. `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints.", 2504 ) 2505 ) 2506 team: str | None = Field( 2507 default=None, 2508 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2509 ) 2510 template_upgrade_available: bool | None = Field( 2511 default=None, 2512 description="True when the agent's last-applied template version is behind the current version of its AgentTemplate config i.e. reapplying the template (a per-agent upgrade) would bring it newer Solution content. Self-clears once the agent is reapplied. Computed on both the list endpoints and single-agent GET. Distinct from `source_solution.upgrade_available`, which compares Solution *versions*: an agent can lag its template (`template_upgrade_available: true`) while the org already holds the latest Solution version (`upgrade_available: false`).", 2513 ) 2514 updated_at: str | None = Field( 2515 default=None, description="When the agent was last modified (ISO 8601)." 2516 ) 2517 user: str | None = Field( 2518 default=None, 2519 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 2520 )
!!! 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.
Access control list for the agent. Contains a grants array where each entry specifies principal_type, principal, and actions. null when no ACL restrictions are applied and the agent is accessible to all members of its scope.
default_model: str | None =
None
Default LLM model identifier used by this agent when no model is specified at runtime (e.g. "claude-3-7-sonnet-latest").
email: str | None =
None
Email address provisioned for this agent. null if email delivery is not configured.
identity: str | None =
None
System-level identity prompt that shapes the agent's persona and behavior.
last_applied_template_config: str | None =
None
ID of the AgentTemplate config (cfg_...) this agent was last provisioned or updated from. null for manually created agents.
lookup_key: str | None =
None
Stable, user-defined identifier for this agent within the application. Unique per app.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.
org: str | None =
None
ID of the organization this agent belongs to (org_...). null if the agent is not org-scoped.
org_name: str | None =
None
Display name of the organization this agent belongs to. null when the agent is not org-scoped or when the org association was not preloaded.
originator: str | None =
None
Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).
phone_number: str | None =
None
Phone number provisioned for this agent. null if SMS is not configured.
sandbox: str | None =
None
ID of the sandbox environment this agent is scoped to (dsb_...). null in production deployments.
Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes upgrade_available, latest_version, and latest_solution so you can render an upgrade badge without a separate dry-run call. null for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints.
team: str | None =
None
ID of the team that owns this agent (tem_...). null if the agent is not team-scoped.
template_upgrade_available: bool | None =
None
True when the agent's last-applied template version is behind the current version of its AgentTemplate config i.e. reapplying the template (a per-agent upgrade) would bring it newer Solution content. Self-clears once the agent is reapplied. Computed on both the list endpoints and single-agent GET. Distinct from source_solution.upgrade_available, which compares Solution versions: an agent can lag its template (template_upgrade_available: true) while the org already holds the latest Solution version (upgrade_available: false).
class
OrgThreadListResponseDataItemSettings(pydantic.main.BaseModel):
2523class OrgThreadListResponseDataItemSettings(BaseModel): 2524 agent_enabled: bool | None = Field( 2525 default=None, 2526 description="Whether the AI agent is active for this thread. `true` enables AI responses; `false` disables them. Defaults to `true` when settings have not been explicitly configured. `null` when a client explicitly cleared the setting.", 2527 )
!!! 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
OrgThreadListResponseDataItem(pydantic.main.BaseModel):
2530class OrgThreadListResponseDataItem(BaseModel): 2531 agent_user: str | None = Field( 2532 default=None, 2533 description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", 2534 ) 2535 created_at: str | None = Field( 2536 default=None, description="When the thread was created (ISO 8601)." 2537 ) 2538 creator: str | dict[str, Any] | None = Field( 2539 default=None, 2540 description="User who created this thread. Returns a user ID (`usr_...`) by default, or an expanded user object when the association is loaded. `null` if the creator is unknown.", 2541 ) 2542 description: str | None = Field( 2543 default=None, 2544 description="Optional description or purpose statement for the thread. `null` if not set.", 2545 ) 2546 id: str = Field(..., description="Thread ID (`thr_...`).") 2547 is_channel: bool | None = Field( 2548 default=None, 2549 description="Whether this thread operates as a channel a multi-member broadcast-style conversation.", 2550 ) 2551 is_default: bool | None = Field( 2552 default=None, 2553 description="Whether this is the default thread for its owner. Each user or team has at most one default thread.", 2554 ) 2555 is_transient: bool | None = Field( 2556 default=None, 2557 description="Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.", 2558 ) 2559 is_unlisted: bool | None = Field( 2560 default=None, 2561 description="Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.", 2562 ) 2563 key: str | None = Field( 2564 default=None, 2565 description="Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", 2566 ) 2567 kind: str | None = Field( 2568 default=None, 2569 description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"feed"` for a post feed with inline replies, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` and `feed` are explicit creation options; mirror kinds are server-derived.', 2570 ) 2571 last_activity: str | None = Field( 2572 default=None, 2573 description="When the most recent message was posted in this thread, falling back to the thread's creation time if it has no messages. Always populated on thread list endpoints (which order by it, after default threads); `null` on endpoints that don't compute activity enrichment.", 2574 ) 2575 last_message_preview: str | None = Field( 2576 default=None, 2577 description="Single-line snippet of the most recent message's text content (first non-empty line, truncated to 140 characters). Populated on thread list endpoints alongside `last_activity`; `null` when the thread has no messages, the latest message has no text content (e.g. attachment-only), or the endpoint doesn't compute activity enrichment.", 2578 ) 2579 last_message_sender: str | None = Field( 2580 default=None, 2581 description="Display name of the sender of the most recent message the same message `last_message_preview` snippets. Populated on thread list endpoints; `null` when the thread has no messages or the endpoint doesn't compute activity enrichment.", 2582 ) 2583 metadata: dict[str, Any] | None = Field( 2584 default=None, 2585 description="Arbitrary key-value metadata attached to the thread. Shape is application-defined; `null` if no metadata has been set.", 2586 ) 2587 muted: bool | None = Field( 2588 default=None, 2589 description="Whether the authenticated user has muted notifications for this thread. `true` suppresses all notification delivery.", 2590 ) 2591 org: str | None = Field( 2592 default=None, 2593 description="ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", 2594 ) 2595 parent_message: OrgThreadListResponseDataItemParentMessage | None = Field( 2596 default=None, 2597 description="The message that spawned this thread as a sub-thread. `null` for top-level threads.", 2598 ) 2599 participant: list[str] | None = Field( 2600 default=None, 2601 description="Array of participant user IDs (`usr_...`) who are members of this thread.", 2602 ) 2603 participants: list[OrgThreadListResponseDataItemParticipantsItem] | None = Field( 2604 default=None, 2605 description="Expanded participant user objects for each member of this thread. Populated only when the association is loaded.", 2606 ) 2607 participating_actor: list[str] | None = Field( 2608 default=None, 2609 description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", 2610 ) 2611 participating_agents: list[OrgThreadListResponseDataItemParticipatingAgentsItem] | None = Field( 2612 default=None, 2613 description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", 2614 ) 2615 role: str | None = Field( 2616 default=None, 2617 description='The authenticated user\'s membership role in this thread, e.g. `"owner"`, `"member"`, or `"viewer"`. `null` if the user is not a member.', 2618 ) 2619 sandbox: str | None = Field( 2620 default=None, 2621 description="ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", 2622 ) 2623 settings: OrgThreadListResponseDataItemSettings | None = Field( 2624 default=None, 2625 description="Per-thread configuration settings controlling AI agent behavior for this thread.", 2626 ) 2627 slug: str | None = Field( 2628 default=None, 2629 description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", 2630 ) 2631 sub_threads: list[dict[str, Any]] | None = Field( 2632 default=None, 2633 description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", 2634 ) 2635 tags: list[str] | None = Field( 2636 default=None, 2637 description='Status tags on the thread (e.g. `"blocked"`, `"needs-review"`). Edited by any thread participant via the `/threads/:thread/tags` endpoints and filterable on the thread list endpoints. Empty array if none set.', 2638 ) 2639 team: str | None = Field( 2640 default=None, 2641 description="ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", 2642 ) 2643 title: str | None = Field( 2644 default=None, 2645 description="Human-readable name of the thread. `null` if no title has been set.", 2646 ) 2647 ttl: str | None = Field( 2648 default=None, 2649 description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", 2650 ) 2651 unread_count: int | None = Field( 2652 default=None, 2653 description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", 2654 ) 2655 updated_at: str | None = Field( 2656 default=None, description="When the thread was last modified (ISO 8601)." 2657 ) 2658 user: str | None = Field( 2659 default=None, 2660 description="ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", 2661 ) 2662 visibility: Literal["team", "restricted", "private", "org"] = Field( 2663 ..., 2664 description="Who can read the thread: `team` for every owning-team member, `restricted` for team-readable threads with an explicit roster, `private` for roster-only access, or `org` for every member of the owning organization.", 2665 )
!!! 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_user: str | None =
None
ID of the agent that owns this thread (agt_...). null for user-owned or team-owned threads.
creator: str | dict[str, typing.Any] | None =
None
User who created this thread. Returns a user ID (usr_...) by default, or an expanded user object when the association is loaded. null if the creator is unknown.
description: str | None =
None
Optional description or purpose statement for the thread. null if not set.
is_channel: bool | None =
None
Whether this thread operates as a channel a multi-member broadcast-style conversation.
is_default: bool | None =
None
Whether this is the default thread for its owner. Each user or team has at most one default thread.
is_transient: bool | None =
None
Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.
is_unlisted: bool | None =
None
Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.
key: str | None =
None
Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. null if not set.
kind: str | None =
None
Thread subtype: "standard" for ordinary threads, "personal" for a user-and-owned-agents roster, "feed" for a post feed with inline replies, "slack_mirror" for the membership-strict mirror of a Slack channel, or "slashwork_mirror" for the membership-strict mirror of a Slashwork group. personal and feed are explicit creation options; mirror kinds are server-derived.
last_activity: str | None =
None
When the most recent message was posted in this thread, falling back to the thread's creation time if it has no messages. Always populated on thread list endpoints (which order by it, after default threads); null on endpoints that don't compute activity enrichment.
last_message_preview: str | None =
None
Single-line snippet of the most recent message's text content (first non-empty line, truncated to 140 characters). Populated on thread list endpoints alongside last_activity; null when the thread has no messages, the latest message has no text content (e.g. attachment-only), or the endpoint doesn't compute activity enrichment.
last_message_sender: str | None =
None
Display name of the sender of the most recent message the same message last_message_preview snippets. Populated on thread list endpoints; null when the thread has no messages or the endpoint doesn't compute activity enrichment.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the thread. Shape is application-defined; null if no metadata has been set.
muted: bool | None =
None
Whether the authenticated user has muted notifications for this thread. true suppresses all notification delivery.
org: str | None =
None
ID of the organization this thread belongs to (org_...). null for threads outside an org context.
participant: list[str] | None =
None
Array of participant user IDs (usr_...) who are members of this thread.
Expanded participant user objects for each member of this thread. Populated only when the association is loaded.
participating_actor: list[str] | None =
None
Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.
Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.
role: str | None =
None
The authenticated user's membership role in this thread, e.g. "owner", "member", or "viewer". null if the user is not a member.
sandbox: str | None =
None
ID of the developer sandbox this thread is scoped to (dsb_...). null for production threads.
slug: str | None =
None
URL-safe slug for the thread, used in human-readable permalinks. null if not assigned.
sub_threads: list[dict[str, typing.Any]] | None =
None
Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.
team: str | None =
None
ID of the team that owns this thread (team_...). null for user-owned or agent-owned threads.
ttl: str | None =
None
Offset-free expiry timestamp after which the thread may be automatically cleaned up. null if the thread does not expire.
unread_count: int | None =
None
Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.
class
OrgThreadListResponse(pydantic.main.BaseModel):
2668class OrgThreadListResponse(BaseModel): 2669 """ 2670 Successful response 2671 """ 2672 2673 data: list[OrgThreadListResponseDataItem] = Field( 2674 ..., description="Array of org-visibility thread objects." 2675 )
Successful response
class
OrgListResponseDataItem(pydantic.main.BaseModel):
2678class OrgListResponseDataItem(BaseModel): 2679 domain: str | None = Field( 2680 default=None, 2681 description="Company domain. For personal orgs, the owner email is returned only to a viewer in that org.", 2682 ) 2683 id: str = Field(..., description="Organization ID (`org_...`).") 2684 kind: Literal["company", "personal"] = Field( 2685 ..., description="Whether this is a company-domain org or a person-owned personal org." 2686 ) 2687 name: str = Field(..., description="Display name of the organization.")
!!! 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.
domain: str | None =
None
Company domain. For personal orgs, the owner email is returned only to a viewer in that org.
class
OrgListResponse(pydantic.main.BaseModel):
2690class OrgListResponse(BaseModel): 2691 """ 2692 Successful response 2693 """ 2694 2695 data: list[OrgListResponseDataItem] = Field( 2696 ..., description="Array of organization objects for the current page." 2697 ) 2698 has_next: bool | None = Field( 2699 default=None, description="`true` when a subsequent page exists; `false` on the last page." 2700 ) 2701 has_prev: bool | None = Field( 2702 default=None, description="`true` when a previous page exists; `false` on the first page." 2703 ) 2704 page: int | None = Field(default=None, description="The current page number returned.") 2705 page_size: int | None = Field( 2706 default=None, description="The number of results per page used for this response." 2707 ) 2708 total_entries: int | None = Field( 2709 default=None, 2710 description="Total number of organizations matching the query across all pages.", 2711 ) 2712 total_pages: int | None = Field( 2713 default=None, description="Total number of pages for the current query and page size." 2714 )
Successful response
class
OrgArtifactsResponseDataItemAclAddItem(pydantic.main.BaseModel):
2717class OrgArtifactsResponseDataItemAclAddItem(BaseModel): 2718 actions: list[str] = Field( 2719 ..., 2720 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2721 ) 2722 principal: str | None = Field( 2723 default=None, 2724 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 2725 ) 2726 principal_type: str = Field( 2727 ..., 2728 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2729 )
!!! 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.
actions: list[str] =
PydanticUndefined
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None =
None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
OrgArtifactsResponseDataItemAclGrantsItem(pydantic.main.BaseModel):
2732class OrgArtifactsResponseDataItemAclGrantsItem(BaseModel): 2733 actions: list[str] = Field( 2734 ..., 2735 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 2736 ) 2737 principal: str | None = Field( 2738 default=None, 2739 description='The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.', 2740 ) 2741 principal_type: str = Field( 2742 ..., 2743 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2744 )
!!! 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.
actions: list[str] =
PydanticUndefined
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None =
None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
OrgArtifactsResponseDataItemAclRemoveItem(pydantic.main.BaseModel):
2747class OrgArtifactsResponseDataItemAclRemoveItem(BaseModel): 2748 principal: str | None = Field( 2749 default=None, 2750 description='The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.', 2751 ) 2752 principal_type: str = Field( 2753 ..., 2754 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 2755 )
!!! 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.
principal: str | None =
None
The identifier of the principal to remove. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role". Omit when principal_type is "everyone".
class
OrgArtifactsResponseDataItemAcl(pydantic.main.BaseModel):
2758class OrgArtifactsResponseDataItemAcl(BaseModel): 2759 add: list[OrgArtifactsResponseDataItemAclAddItem] | None = Field( 2760 default=None, 2761 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 2762 ) 2763 grants: list[OrgArtifactsResponseDataItemAclGrantsItem] | None = Field( 2764 default=None, 2765 description="Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.", 2766 ) 2767 remove: list[OrgArtifactsResponseDataItemAclRemoveItem] | None = Field( 2768 default=None, 2769 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 2770 )
!!! 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.
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
OrgArtifactsResponseDataItemImageSource(pydantic.main.BaseModel):
2773class OrgArtifactsResponseDataItemImageSource(BaseModel): 2774 file: str | None = Field( 2775 default=None, 2776 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2777 ) 2778 height: int | None = Field( 2779 default=None, description="Height of the image in pixels. `null` if not known." 2780 ) 2781 media: str | None = Field( 2782 default=None, 2783 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2784 ) 2785 mime_type: str | None = Field( 2786 default=None, 2787 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2788 ) 2789 refresh_url: str | None = Field( 2790 default=None, 2791 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.", 2792 ) 2793 url: str | None = Field( 2794 default=None, 2795 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.", 2796 ) 2797 width: int | None = Field( 2798 default=None, description="Width of the image in pixels. `null` if not known." 2799 )
!!! 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
OrgArtifactsResponseDataItem(pydantic.main.BaseModel):
2802class OrgArtifactsResponseDataItem(BaseModel): 2803 acl: OrgArtifactsResponseDataItemAcl | None = Field( 2804 default=None, 2805 description="Access control list for the artifact. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions` (`read`, `write`). `null` when the artifact has no grants or the viewer is not its owner.", 2806 ) 2807 agent: str | None = Field( 2808 default=None, 2809 description="ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.", 2810 ) 2811 content_type: str | None = Field( 2812 default=None, 2813 description='MIME type of the current version\'s file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.', 2814 ) 2815 created_at: datetime | None = Field( 2816 default=None, description="When the artifact was first created (ISO 8601)." 2817 ) 2818 current_version: str | None = Field( 2819 default=None, 2820 description="ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.", 2821 ) 2822 description: str | None = Field( 2823 default=None, 2824 description="Optional longer description of the artifact's contents or purpose. `null` if not set.", 2825 ) 2826 file: str | None = Field( 2827 default=None, 2828 description="Storage file ID for the current version (`fil_...`). `null` if no file is attached.", 2829 ) 2830 file_name: str | None = Field( 2831 default=None, 2832 description='Original filename of the current version\'s file, e.g. `"output.csv"`. `null` if no file is attached.', 2833 ) 2834 file_url: str | None = Field( 2835 default=None, 2836 description="Short-lived signed URL for downloading the current version's file. `null` if no file is attached.", 2837 ) 2838 group_key: str | None = Field( 2839 default=None, 2840 description="Optional nonunique, case-sensitive grouping key, limited to 1024 UTF-8 bytes. Null when unset; belongs to the artifact, not a content version.", 2841 ) 2842 id: str = Field(..., description="Artifact ID (`art_...`).") 2843 image_source: OrgArtifactsResponseDataItemImageSource | None = Field( 2844 default=None, 2845 description='Image source metadata for rendering the current version\'s file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.', 2846 ) 2847 name: str | None = Field( 2848 default=None, 2849 description='Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.', 2850 ) 2851 org: str | None = Field( 2852 default=None, description="ID of the organization this artifact belongs to (`org_...`)." 2853 ) 2854 sandbox: str | None = Field( 2855 default=None, 2856 description="Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.", 2857 ) 2858 system: bool | None = Field( 2859 default=None, 2860 description="True when the artifact has no user, team, or agent owner. An organization may own a system artifact.", 2861 ) 2862 team: str | None = Field( 2863 default=None, 2864 description="ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.", 2865 ) 2866 thread: str | None = Field( 2867 default=None, 2868 description="ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.", 2869 ) 2870 updated_at: datetime | None = Field( 2871 default=None, description="When the artifact record was last modified (ISO 8601)." 2872 ) 2873 user: str | None = Field( 2874 default=None, 2875 description="ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.", 2876 ) 2877 version: int | None = Field( 2878 default=None, 2879 description="Current version number of the artifact. Increments each time a new version is published.", 2880 )
!!! 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.
Access control list for the artifact. Contains a grants array where each entry specifies principal_type, principal, and actions (read, write). null when the artifact has no grants or the viewer is not its owner.
agent: str | None =
None
ID of the agent that produced this artifact (agt_...). null if not agent-produced.
content_type: str | None =
None
MIME type of the current version's file, e.g. "text/csv" or "image/png". null if no file is attached.
current_version: str | None =
None
ID of the current (latest published) artifact version (artv_...). null if no version has been published.
description: str | None =
None
Optional longer description of the artifact's contents or purpose. null if not set.
file: str | None =
None
Storage file ID for the current version (fil_...). null if no file is attached.
file_name: str | None =
None
Original filename of the current version's file, e.g. "output.csv". null if no file is attached.
file_url: str | None =
None
Short-lived signed URL for downloading the current version's file. null if no file is attached.
group_key: str | None =
None
Optional nonunique, case-sensitive grouping key, limited to 1024 UTF-8 bytes. Null when unset; belongs to the artifact, not a content version.
Image source metadata for rendering the current version's file inline. Present only when content_type starts with "image/". null otherwise.
sandbox: str | None =
None
Identifier of the sandbox environment associated with this artifact. null if not sandbox-scoped.
system: bool | None =
None
True when the artifact has no user, team, or agent owner. An organization may own a system artifact.
thread: str | None =
None
ID of the thread in which this artifact was created (thr_...). null if not thread-scoped.
class
OrgArtifactsResponse(pydantic.main.BaseModel):
2883class OrgArtifactsResponse(BaseModel): 2884 """ 2885 Successful response 2886 """ 2887 2888 after_cursor: str | None = None 2889 before_cursor: str | None = Field( 2890 default=None, description="Always null; pagination is forward-only." 2891 ) 2892 data: list[OrgArtifactsResponseDataItem] 2893 has_more: bool
Successful response
class
OrgLinkedAccountsResponseDataItem(pydantic.main.BaseModel):
2896class OrgLinkedAccountsResponseDataItem(BaseModel): 2897 account_id: str = Field( 2898 ..., description="The service's name for the account: the login, for GitHub." 2899 ) 2900 provider: str = Field( 2901 ..., description='Service the account is on. Currently always `"github"`.' 2902 ) 2903 user: str = Field(..., description="User ID (`usr_...`) the account belongs to.")
!!! 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
OrgLinkedAccountsResponse(pydantic.main.BaseModel):
2906class OrgLinkedAccountsResponse(BaseModel): 2907 """ 2908 Successful response 2909 """ 2910 2911 after_cursor: str | None = None 2912 before_cursor: str | None = Field( 2913 default=None, description="Always null; pagination is forward-only." 2914 ) 2915 data: list[OrgLinkedAccountsResponseDataItem] = Field( 2916 ..., description="Linked accounts, by user." 2917 ) 2918 has_more: bool
Successful response
class
OrgTaskEpicsResponseDataItemNextReadyItem(pydantic.main.BaseModel):
2921class OrgTaskEpicsResponseDataItemNextReadyItem(BaseModel): 2922 id: str 2923 name: str 2924 priority: int 2925 status: str
!!! 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
OrgTaskEpicsResponseDataItemRootBlockersItem(pydantic.main.BaseModel):
2928class OrgTaskEpicsResponseDataItemRootBlockersItem(BaseModel): 2929 downstream_count: int 2930 id: str 2931 name: str 2932 priority: int 2933 status: str
!!! 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
OrgTaskEpicsResponseDataItem(pydantic.main.BaseModel):
2936class OrgTaskEpicsResponseDataItem(BaseModel): 2937 blocked_count: int 2938 counts: dict[str, Any] = Field( 2939 ..., description="Task counts keyed by status, including closed tasks." 2940 ) 2941 epic: str 2942 next_ready: list[OrgTaskEpicsResponseDataItemNextReadyItem] 2943 root_blockers: list[OrgTaskEpicsResponseDataItemRootBlockersItem] 2944 root_blockers_partial: bool = Field( 2945 ..., description="True when root ranking used a truncated in-epic graph." 2946 ) 2947 top_open_priority: int | None = None 2948 updated_at: datetime
!!! 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.
counts: dict[str, typing.Any] =
PydanticUndefined
Task counts keyed by status, including closed tasks.
class
OrgTaskEpicsResponse(pydantic.main.BaseModel):
2951class OrgTaskEpicsResponse(BaseModel): 2952 """ 2953 Successful response 2954 """ 2955 2956 after_cursor: str | None = None 2957 before_cursor: str | None = None 2958 data: list[OrgTaskEpicsResponseDataItem] 2959 has_more: bool 2960 no_epic_open_count: int
Successful response
class
AsyncOrgTaskResource:
2963class AsyncOrgTaskResource: 2964 def __init__(self, http: HttpClient): 2965 self._http = http 2966 2967 async def list( 2968 self, 2969 org: str, 2970 *, 2971 status: str | None = None, 2972 owner_user: str | None = None, 2973 owner_agent: str | None = None, 2974 priority: int | None = None, 2975 tag: str | None = None, 2976 parent: str | None = None, 2977 source_scope: str | None = None, 2978 source_type: str | None = None, 2979 source_id: str | None = None, 2980 epic: str | None = None, 2981 search: str | None = None, 2982 sort: str | None = None, 2983 order: str | None = None, 2984 due_before: str | None = None, 2985 due_after: str | None = None, 2986 overdue: bool | None = None, 2987 ready: bool | None = None, 2988 attention: bool | None = None, 2989 limit: int | None = None, 2990 after_cursor: str | None = None, 2991 ) -> OrgTaskListResponse: 2992 """ 2993 List an organization's tasks 2994 Returns org-owned tasks for the specified organization: rows with the org 2995 tenant and no narrower user/team/agent scope. Explicitly personal, team, or 2996 agent tasks are excluded here; list those via the user/team collections or 2997 fetch them directly when authorized. 2998 Every organization member may list. App-scoped developer and 2999 server-to-server callers supply the org in the route. 3000 3001 Args: 3002 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3003 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3004 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3005 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3006 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3007 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3008 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3009 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3010 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3011 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3012 epic: Return only tasks with this exact epic label. 3013 search: Restrict results to tasks whose name or description contains this string. 3014 sort: Sort key. One of `"created"` (default most recently created first), `"due_date"` (soonest due first; tasks without a due date always sort last), or `"priority"` (most urgent first). Ties break by most recently created. 3015 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3016 due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. 3017 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3018 overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. 3019 ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. 3020 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3021 limit: Maximum number of tasks to return. Capped at 100. 3022 after_cursor: Opaque cursor returned by the previous page. 3023 3024 Returns: 3025 Successful response 3026 """ 3027 query: dict[str, object] = {} 3028 if status is not None: 3029 query["status"] = status 3030 if owner_user is not None: 3031 query["owner_user"] = owner_user 3032 if owner_agent is not None: 3033 query["owner_agent"] = owner_agent 3034 if priority is not None: 3035 query["priority"] = priority 3036 if tag is not None: 3037 query["tag"] = tag 3038 if parent is not None: 3039 query["parent"] = parent 3040 if source_scope is not None: 3041 query["source_scope"] = source_scope 3042 if source_type is not None: 3043 query["source_type"] = source_type 3044 if source_id is not None: 3045 query["source_id"] = source_id 3046 if epic is not None: 3047 query["epic"] = epic 3048 if search is not None: 3049 query["search"] = search 3050 if sort is not None: 3051 query["sort"] = sort 3052 if order is not None: 3053 query["order"] = order 3054 if due_before is not None: 3055 query["due_before"] = due_before 3056 if due_after is not None: 3057 query["due_after"] = due_after 3058 if overdue is not None: 3059 query["overdue"] = overdue 3060 if ready is not None: 3061 query["ready"] = ready 3062 if attention is not None: 3063 query["attention"] = attention 3064 if limit is not None: 3065 query["limit"] = limit 3066 if after_cursor is not None: 3067 query["after_cursor"] = after_cursor 3068 return await self._http.request( 3069 f"/api/v1/orgs/{org}/tasks", 3070 query=query, 3071 response_type=OrgTaskListResponse, 3072 ) 3073 3074 async def create(self, org: str, input: OrgTaskCreateInput) -> Task: 3075 """ 3076 Create a task for an organization 3077 Creates a new org-owned task (org tenant, no narrower user/team/agent 3078 scope) and returns the full task object. User-authenticated calls are 3079 attributed to the authenticated user or agent. App-scoped developer and 3080 server-to-server callers must provide an explicit `user` or `agent` actor 3081 for the organization. Every referenced principal is validated against the 3082 app and organization before creation. 3083 3084 Args: 3085 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3086 input: Request body. 3087 input.agent: Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization. 3088 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3089 input.user: Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`. 3090 3091 Returns: 3092 The newly created task. 3093 """ 3094 return await self._http.request( 3095 f"/api/v1/orgs/{org}/tasks", 3096 method="POST", 3097 body=input, 3098 response_type=Task, 3099 ) 3100 3101 async def blocker_cycles( 3102 self, org: str, *, limit: int | None = None, after_cursor: str | None = None 3103 ) -> OrgTaskBlockerCyclesResponse: 3104 """ 3105 List task blocker cycles for an organization 3106 Runs an on-demand diagnostic over unfinished org-owned tasks for the 3107 specified organization and returns a forward cursor-paginated page of 3108 complete cyclic blocker components. Detection is bounded to owners with at 3109 most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent 3110 task updates, lease acquisition, or completion. 3111 3112 Args: 3113 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3114 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3115 after_cursor: Opaque cursor returned by the preceding page. 3116 3117 Returns: 3118 Successful response 3119 """ 3120 query: dict[str, object] = {} 3121 if limit is not None: 3122 query["limit"] = limit 3123 if after_cursor is not None: 3124 query["after_cursor"] = after_cursor 3125 return await self._http.request( 3126 f"/api/v1/orgs/{org}/tasks/blocker_cycles", 3127 query=query, 3128 response_type=OrgTaskBlockerCyclesResponse, 3129 ) 3130 3131 async def by_source(self, org: str, input: OrgTaskBySourceInput) -> TaskEnsureResult: 3132 """ 3133 Find or create a task by source 3134 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3135 3136 Args: 3137 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3138 input: Request body. 3139 input.agent: Explicit acting agent for privileged callers. 3140 input.description: Initial task description. 3141 input.epic: Initial epic grouping. 3142 input.name: Initial task name. 3143 input.source_id: Source identity, for example owner/repo#123. 3144 input.source_scope: Source scope, for example github. 3145 input.source_type: Source type, for example pull_request. 3146 input.status: Initial task status. 3147 input.team: Team owner. 3148 input.user: User owner, or explicit acting user on a team route. 3149 3150 Returns: 3151 The task and whether this request created it. 3152 """ 3153 return await self._http.request( 3154 f"/api/v1/orgs/{org}/tasks/by-source", 3155 method="PUT", 3156 body=input, 3157 response_type=TaskEnsureResult, 3158 ) 3159 3160 async def metrics(self, org: str, *, days: int | None = None) -> OrgTaskMetricsResponse: 3161 """ 3162 Get task activity metrics for an organization 3163 Returns task activity metrics scoped to org-owned tasks (org tenant, no 3164 narrower user/team/agent scope). `open` counts currently open or 3165 in-progress org tasks, `created` counts tasks inserted in the UTC-day 3166 window, and `completed` counts tasks whose `closed_at` falls in that window 3167 while still in a closed status. Hard-deleted tasks are absent from the 3168 projection and therefore omitted. The daily series is zero-filled across 3169 the requested window and includes reconstructed end-of-day `open` stock. 3170 Any organization member may read this count-only summary. Requests from 3171 callers without org access return 404 so organization existence is not 3172 disclosed. 3173 3174 Args: 3175 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3176 days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30. 3177 3178 Returns: 3179 Successful response 3180 """ 3181 query: dict[str, object] = {} 3182 if days is not None: 3183 query["days"] = days 3184 return await self._http.request( 3185 f"/api/v1/orgs/{org}/tasks/metrics", 3186 query=query, 3187 response_type=OrgTaskMetricsResponse, 3188 ) 3189 3190 async def ready( 3191 self, 3192 org: str, 3193 *, 3194 explain: bool | None = None, 3195 assigned_to_me: bool | None = None, 3196 source_scope: str | None = None, 3197 source_type: str | None = None, 3198 source_id: str | None = None, 3199 epic: str | None = None, 3200 limit: int | None = None, 3201 after_cursor: str | None = None, 3202 ) -> OrgTaskReadyResponse: 3203 """ 3204 List an organization's ready tasks 3205 Returns open org-owned tasks with no unfinished blockers and no active 3206 session lease. Readiness is calculated by the server from the current task 3207 projection. It is a snapshot, not a reservation; claim a task lease before 3208 starting work. 3209 Results are ordered by priority (0, the most urgent, first), then oldest 3210 first, so the first page is always the most urgent ready work. 3211 Pass `explain=true` to include every open task with a stable readiness reason. 3212 3213 Args: 3214 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3215 explain: Include blocked and actively leased open tasks with exclusion reasons. 3216 assigned_to_me: Only include tasks assigned to the authenticated user. 3217 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3218 source_type: Only include tasks whose source matches this object kind. 3219 source_id: Only include tasks whose source matches this object identity. 3220 epic: Only include tasks with this exact epic label. 3221 limit: Maximum number of readiness entries to return. Capped at 100. 3222 after_cursor: Opaque cursor returned by the previous page. 3223 3224 Returns: 3225 Successful response 3226 """ 3227 query: dict[str, object] = {} 3228 if explain is not None: 3229 query["explain"] = explain 3230 if assigned_to_me is not None: 3231 query["assigned_to_me"] = assigned_to_me 3232 if source_scope is not None: 3233 query["source_scope"] = source_scope 3234 if source_type is not None: 3235 query["source_type"] = source_type 3236 if source_id is not None: 3237 query["source_id"] = source_id 3238 if epic is not None: 3239 query["epic"] = epic 3240 if limit is not None: 3241 query["limit"] = limit 3242 if after_cursor is not None: 3243 query["after_cursor"] = after_cursor 3244 return await self._http.request( 3245 f"/api/v1/orgs/{org}/tasks/ready", 3246 query=query, 3247 response_type=OrgTaskReadyResponse, 3248 ) 3249 3250 async def search( 3251 self, 3252 org: str, 3253 *, 3254 q: str | None = None, 3255 query: str | None = None, 3256 status: str | None = None, 3257 owner_user: str | None = None, 3258 owner_agent: str | None = None, 3259 priority: int | None = None, 3260 tag: str | None = None, 3261 parent: str | None = None, 3262 source_scope: str | None = None, 3263 source_type: str | None = None, 3264 source_id: str | None = None, 3265 epic: str | None = None, 3266 limit: int | None = None, 3267 after_cursor: str | None = None, 3268 ) -> OrgTaskSearchResponse: 3269 """ 3270 Search an organization's tasks 3271 Performs a full-text search over org-owned tasks for the specified 3272 organization and returns matching results. Combine `q` with the optional 3273 filters to narrow the result set further. When no query is provided, the 3274 endpoint behaves like a filtered list. 3275 The `query` field in the response echoes the effective search query. 3276 Explicitly personal, team, or agent tasks are excluded here. 3277 3278 Args: 3279 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3280 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3281 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3282 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3283 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3284 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3285 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3286 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3287 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3288 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3289 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3290 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3291 epic: Return only tasks with this exact epic label. 3292 limit: Maximum number of tasks to return. Capped at 100. 3293 after_cursor: Opaque cursor returned by the previous page. 3294 3295 Returns: 3296 Successful response 3297 """ 3298 query: dict[str, object] = {} 3299 if q is not None: 3300 query["q"] = q 3301 if query is not None: 3302 query["query"] = query 3303 if status is not None: 3304 query["status"] = status 3305 if owner_user is not None: 3306 query["owner_user"] = owner_user 3307 if owner_agent is not None: 3308 query["owner_agent"] = owner_agent 3309 if priority is not None: 3310 query["priority"] = priority 3311 if tag is not None: 3312 query["tag"] = tag 3313 if parent is not None: 3314 query["parent"] = parent 3315 if source_scope is not None: 3316 query["source_scope"] = source_scope 3317 if source_type is not None: 3318 query["source_type"] = source_type 3319 if source_id is not None: 3320 query["source_id"] = source_id 3321 if epic is not None: 3322 query["epic"] = epic 3323 if limit is not None: 3324 query["limit"] = limit 3325 if after_cursor is not None: 3326 query["after_cursor"] = after_cursor 3327 return await self._http.request( 3328 f"/api/v1/orgs/{org}/tasks/search", 3329 query=query, 3330 response_type=OrgTaskSearchResponse, 3331 )
AsyncOrgTaskResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, org: str, *, status: str | None = None, owner_user: str | None = None, owner_agent: str | None = None, priority: int | None = None, tag: str | None = None, parent: str | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, epic: str | None = None, search: str | None = None, sort: str | None = None, order: str | None = None, due_before: str | None = None, due_after: str | None = None, overdue: bool | None = None, ready: bool | None = None, attention: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskListResponse:
2967 async def list( 2968 self, 2969 org: str, 2970 *, 2971 status: str | None = None, 2972 owner_user: str | None = None, 2973 owner_agent: str | None = None, 2974 priority: int | None = None, 2975 tag: str | None = None, 2976 parent: str | None = None, 2977 source_scope: str | None = None, 2978 source_type: str | None = None, 2979 source_id: str | None = None, 2980 epic: str | None = None, 2981 search: str | None = None, 2982 sort: str | None = None, 2983 order: str | None = None, 2984 due_before: str | None = None, 2985 due_after: str | None = None, 2986 overdue: bool | None = None, 2987 ready: bool | None = None, 2988 attention: bool | None = None, 2989 limit: int | None = None, 2990 after_cursor: str | None = None, 2991 ) -> OrgTaskListResponse: 2992 """ 2993 List an organization's tasks 2994 Returns org-owned tasks for the specified organization: rows with the org 2995 tenant and no narrower user/team/agent scope. Explicitly personal, team, or 2996 agent tasks are excluded here; list those via the user/team collections or 2997 fetch them directly when authorized. 2998 Every organization member may list. App-scoped developer and 2999 server-to-server callers supply the org in the route. 3000 3001 Args: 3002 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3003 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3004 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3005 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3006 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3007 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3008 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3009 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3010 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3011 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3012 epic: Return only tasks with this exact epic label. 3013 search: Restrict results to tasks whose name or description contains this string. 3014 sort: Sort key. One of `"created"` (default most recently created first), `"due_date"` (soonest due first; tasks without a due date always sort last), or `"priority"` (most urgent first). Ties break by most recently created. 3015 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3016 due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. 3017 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3018 overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. 3019 ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. 3020 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3021 limit: Maximum number of tasks to return. Capped at 100. 3022 after_cursor: Opaque cursor returned by the previous page. 3023 3024 Returns: 3025 Successful response 3026 """ 3027 query: dict[str, object] = {} 3028 if status is not None: 3029 query["status"] = status 3030 if owner_user is not None: 3031 query["owner_user"] = owner_user 3032 if owner_agent is not None: 3033 query["owner_agent"] = owner_agent 3034 if priority is not None: 3035 query["priority"] = priority 3036 if tag is not None: 3037 query["tag"] = tag 3038 if parent is not None: 3039 query["parent"] = parent 3040 if source_scope is not None: 3041 query["source_scope"] = source_scope 3042 if source_type is not None: 3043 query["source_type"] = source_type 3044 if source_id is not None: 3045 query["source_id"] = source_id 3046 if epic is not None: 3047 query["epic"] = epic 3048 if search is not None: 3049 query["search"] = search 3050 if sort is not None: 3051 query["sort"] = sort 3052 if order is not None: 3053 query["order"] = order 3054 if due_before is not None: 3055 query["due_before"] = due_before 3056 if due_after is not None: 3057 query["due_after"] = due_after 3058 if overdue is not None: 3059 query["overdue"] = overdue 3060 if ready is not None: 3061 query["ready"] = ready 3062 if attention is not None: 3063 query["attention"] = attention 3064 if limit is not None: 3065 query["limit"] = limit 3066 if after_cursor is not None: 3067 query["after_cursor"] = after_cursor 3068 return await self._http.request( 3069 f"/api/v1/orgs/{org}/tasks", 3070 query=query, 3071 response_type=OrgTaskListResponse, 3072 )
List an organization's tasks Returns org-owned tasks for the specified organization: rows with the org tenant and no narrower user/team/agent scope. Explicitly personal, team, or agent tasks are excluded here; list those via the user/team collections or fetch them directly when authorized. Every organization member may list. App-scoped developer and server-to-server callers supply the org in the route.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - status: Filter tasks by status. One of
"open","in_progress","in_review", or"done". Omit to return tasks in all statuses. - owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (
usr_...). - owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (
agi_...). - priority: Filter tasks by priority, from 0 (highest) to 4 (lowest).
- tag: Return only tasks carrying this tag (matched against the canonical lowercase form).
- parent: Return only subtasks of the given task (
tsk_...), or passnoneto return only top-level tasks. - source_scope: Return only tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters.
- source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters.
- epic: Return only tasks with this exact epic label.
- search: Restrict results to tasks whose name or description contains this string.
- sort: Sort key. One of
"created"(default most recently created first),"due_date"(soonest due first; tasks without a due date always sort last), or"priority"(most urgent first). Ties break by most recently created. - order: Sort direction,
"asc"or"desc". Defaults to"desc"forcreatedand"asc"fordue_dateandpriority. - due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (
2026-08-01T00:00:00Z) or date (2026-08-01, meaning midnight UTC). Tasks without a due date are excluded. - due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded.
- overdue: When
true, return only overdue tasks: a due date before the current UTC day and a status other than"done". A task due today is not overdue. - ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work.
- attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry.
- limit: Maximum number of tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
async def
create( self, org: str, input: OrgTaskCreateInput) -> archastro.platform.types.tasks.Task:
3074 async def create(self, org: str, input: OrgTaskCreateInput) -> Task: 3075 """ 3076 Create a task for an organization 3077 Creates a new org-owned task (org tenant, no narrower user/team/agent 3078 scope) and returns the full task object. User-authenticated calls are 3079 attributed to the authenticated user or agent. App-scoped developer and 3080 server-to-server callers must provide an explicit `user` or `agent` actor 3081 for the organization. Every referenced principal is validated against the 3082 app and organization before creation. 3083 3084 Args: 3085 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3086 input: Request body. 3087 input.agent: Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization. 3088 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3089 input.user: Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`. 3090 3091 Returns: 3092 The newly created task. 3093 """ 3094 return await self._http.request( 3095 f"/api/v1/orgs/{org}/tasks", 3096 method="POST", 3097 body=input, 3098 response_type=Task, 3099 )
Create a task for an organization
Creates a new org-owned task (org tenant, no narrower user/team/agent
scope) and returns the full task object. User-authenticated calls are
attributed to the authenticated user or agent. App-scoped developer and
server-to-server callers must provide an explicit user or agent actor
for the organization. Every referenced principal is validated against the
app and organization before creation.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - input: Request body.
- input.agent: Explicit acting agent (
agi_...) for a developer or server-to-server call. Mutually exclusive with an actinguser; the agent must belong to the organization. - input.task: Attributes for the task to create.
nameis required; all other fields are optional. - input.user: Explicit acting user (
usr_...) for a developer or server-to-server call. Mutually exclusive with an actingagent.
Returns:
The newly created task.
async def
blocker_cycles( self, org: str, *, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskBlockerCyclesResponse:
3101 async def blocker_cycles( 3102 self, org: str, *, limit: int | None = None, after_cursor: str | None = None 3103 ) -> OrgTaskBlockerCyclesResponse: 3104 """ 3105 List task blocker cycles for an organization 3106 Runs an on-demand diagnostic over unfinished org-owned tasks for the 3107 specified organization and returns a forward cursor-paginated page of 3108 complete cyclic blocker components. Detection is bounded to owners with at 3109 most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent 3110 task updates, lease acquisition, or completion. 3111 3112 Args: 3113 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3114 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3115 after_cursor: Opaque cursor returned by the preceding page. 3116 3117 Returns: 3118 Successful response 3119 """ 3120 query: dict[str, object] = {} 3121 if limit is not None: 3122 query["limit"] = limit 3123 if after_cursor is not None: 3124 query["after_cursor"] = after_cursor 3125 return await self._http.request( 3126 f"/api/v1/orgs/{org}/tasks/blocker_cycles", 3127 query=query, 3128 response_type=OrgTaskBlockerCyclesResponse, 3129 )
List task blocker cycles for an organization Runs an on-demand diagnostic over unfinished org-owned tasks for the specified organization and returns a forward cursor-paginated page of complete cyclic blocker components. Detection is bounded to owners with at most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent task updates, lease acquisition, or completion.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - limit: Maximum cycle components to return. Defaults to 50; maximum is 100.
- after_cursor: Opaque cursor returned by the preceding page.
Returns:
Successful response
async def
by_source( self, org: str, input: OrgTaskBySourceInput) -> archastro.platform.types.tasks.TaskEnsureResult:
3131 async def by_source(self, org: str, input: OrgTaskBySourceInput) -> TaskEnsureResult: 3132 """ 3133 Find or create a task by source 3134 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3135 3136 Args: 3137 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3138 input: Request body. 3139 input.agent: Explicit acting agent for privileged callers. 3140 input.description: Initial task description. 3141 input.epic: Initial epic grouping. 3142 input.name: Initial task name. 3143 input.source_id: Source identity, for example owner/repo#123. 3144 input.source_scope: Source scope, for example github. 3145 input.source_type: Source type, for example pull_request. 3146 input.status: Initial task status. 3147 input.team: Team owner. 3148 input.user: User owner, or explicit acting user on a team route. 3149 3150 Returns: 3151 The task and whether this request created it. 3152 """ 3153 return await self._http.request( 3154 f"/api/v1/orgs/{org}/tasks/by-source", 3155 method="PUT", 3156 body=input, 3157 response_type=TaskEnsureResult, 3158 )
Find or create a task by source Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - input: Request body.
- input.agent: Explicit acting agent for privileged callers.
- input.description: Initial task description.
- input.epic: Initial epic grouping.
- input.name: Initial task name.
- input.source_id: Source identity, for example owner/repo#123.
- input.source_scope: Source scope, for example github.
- input.source_type: Source type, for example pull_request.
- input.status: Initial task status.
- input.team: Team owner.
- input.user: User owner, or explicit acting user on a team route.
Returns:
The task and whether this request created it.
3160 async def metrics(self, org: str, *, days: int | None = None) -> OrgTaskMetricsResponse: 3161 """ 3162 Get task activity metrics for an organization 3163 Returns task activity metrics scoped to org-owned tasks (org tenant, no 3164 narrower user/team/agent scope). `open` counts currently open or 3165 in-progress org tasks, `created` counts tasks inserted in the UTC-day 3166 window, and `completed` counts tasks whose `closed_at` falls in that window 3167 while still in a closed status. Hard-deleted tasks are absent from the 3168 projection and therefore omitted. The daily series is zero-filled across 3169 the requested window and includes reconstructed end-of-day `open` stock. 3170 Any organization member may read this count-only summary. Requests from 3171 callers without org access return 404 so organization existence is not 3172 disclosed. 3173 3174 Args: 3175 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3176 days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30. 3177 3178 Returns: 3179 Successful response 3180 """ 3181 query: dict[str, object] = {} 3182 if days is not None: 3183 query["days"] = days 3184 return await self._http.request( 3185 f"/api/v1/orgs/{org}/tasks/metrics", 3186 query=query, 3187 response_type=OrgTaskMetricsResponse, 3188 )
Get task activity metrics for an organization
Returns task activity metrics scoped to org-owned tasks (org tenant, no
narrower user/team/agent scope). open counts currently open or
in-progress org tasks, created counts tasks inserted in the UTC-day
window, and completed counts tasks whose closed_at falls in that window
while still in a closed status. Hard-deleted tasks are absent from the
projection and therefore omitted. The daily series is zero-filled across
the requested window and includes reconstructed end-of-day open stock.
Any organization member may read this count-only summary. Requests from
callers without org access return 404 so organization existence is not
disclosed.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30.
Returns:
Successful response
async def
ready( self, org: str, *, explain: bool | None = None, assigned_to_me: bool | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, epic: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskReadyResponse:
3190 async def ready( 3191 self, 3192 org: str, 3193 *, 3194 explain: bool | None = None, 3195 assigned_to_me: bool | None = None, 3196 source_scope: str | None = None, 3197 source_type: str | None = None, 3198 source_id: str | None = None, 3199 epic: str | None = None, 3200 limit: int | None = None, 3201 after_cursor: str | None = None, 3202 ) -> OrgTaskReadyResponse: 3203 """ 3204 List an organization's ready tasks 3205 Returns open org-owned tasks with no unfinished blockers and no active 3206 session lease. Readiness is calculated by the server from the current task 3207 projection. It is a snapshot, not a reservation; claim a task lease before 3208 starting work. 3209 Results are ordered by priority (0, the most urgent, first), then oldest 3210 first, so the first page is always the most urgent ready work. 3211 Pass `explain=true` to include every open task with a stable readiness reason. 3212 3213 Args: 3214 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3215 explain: Include blocked and actively leased open tasks with exclusion reasons. 3216 assigned_to_me: Only include tasks assigned to the authenticated user. 3217 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3218 source_type: Only include tasks whose source matches this object kind. 3219 source_id: Only include tasks whose source matches this object identity. 3220 epic: Only include tasks with this exact epic label. 3221 limit: Maximum number of readiness entries to return. Capped at 100. 3222 after_cursor: Opaque cursor returned by the previous page. 3223 3224 Returns: 3225 Successful response 3226 """ 3227 query: dict[str, object] = {} 3228 if explain is not None: 3229 query["explain"] = explain 3230 if assigned_to_me is not None: 3231 query["assigned_to_me"] = assigned_to_me 3232 if source_scope is not None: 3233 query["source_scope"] = source_scope 3234 if source_type is not None: 3235 query["source_type"] = source_type 3236 if source_id is not None: 3237 query["source_id"] = source_id 3238 if epic is not None: 3239 query["epic"] = epic 3240 if limit is not None: 3241 query["limit"] = limit 3242 if after_cursor is not None: 3243 query["after_cursor"] = after_cursor 3244 return await self._http.request( 3245 f"/api/v1/orgs/{org}/tasks/ready", 3246 query=query, 3247 response_type=OrgTaskReadyResponse, 3248 )
List an organization's ready tasks
Returns open org-owned tasks with no unfinished blockers and no active
session lease. Readiness is calculated by the server from the current task
projection. It is a snapshot, not a reservation; claim a task lease before
starting work.
Results are ordered by priority (0, the most urgent, first), then oldest
first, so the first page is always the most urgent ready work.
Pass explain=true to include every open task with a stable readiness reason.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - explain: Include blocked and actively leased open tasks with exclusion reasons.
- assigned_to_me: Only include tasks assigned to the authenticated user.
- source_scope: Only include tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Only include tasks whose source matches this object kind.
- source_id: Only include tasks whose source matches this object identity.
- epic: Only include tasks with this exact epic label.
- limit: Maximum number of readiness entries to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
async def
search( self, org: str, *, q: str | None = None, query: str | None = None, status: str | None = None, owner_user: str | None = None, owner_agent: str | None = None, priority: int | None = None, tag: str | None = None, parent: str | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, epic: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskSearchResponse:
3250 async def search( 3251 self, 3252 org: str, 3253 *, 3254 q: str | None = None, 3255 query: str | None = None, 3256 status: str | None = None, 3257 owner_user: str | None = None, 3258 owner_agent: str | None = None, 3259 priority: int | None = None, 3260 tag: str | None = None, 3261 parent: str | None = None, 3262 source_scope: str | None = None, 3263 source_type: str | None = None, 3264 source_id: str | None = None, 3265 epic: str | None = None, 3266 limit: int | None = None, 3267 after_cursor: str | None = None, 3268 ) -> OrgTaskSearchResponse: 3269 """ 3270 Search an organization's tasks 3271 Performs a full-text search over org-owned tasks for the specified 3272 organization and returns matching results. Combine `q` with the optional 3273 filters to narrow the result set further. When no query is provided, the 3274 endpoint behaves like a filtered list. 3275 The `query` field in the response echoes the effective search query. 3276 Explicitly personal, team, or agent tasks are excluded here. 3277 3278 Args: 3279 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3280 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3281 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3282 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3283 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3284 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3285 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3286 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3287 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3288 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3289 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3290 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3291 epic: Return only tasks with this exact epic label. 3292 limit: Maximum number of tasks to return. Capped at 100. 3293 after_cursor: Opaque cursor returned by the previous page. 3294 3295 Returns: 3296 Successful response 3297 """ 3298 query: dict[str, object] = {} 3299 if q is not None: 3300 query["q"] = q 3301 if query is not None: 3302 query["query"] = query 3303 if status is not None: 3304 query["status"] = status 3305 if owner_user is not None: 3306 query["owner_user"] = owner_user 3307 if owner_agent is not None: 3308 query["owner_agent"] = owner_agent 3309 if priority is not None: 3310 query["priority"] = priority 3311 if tag is not None: 3312 query["tag"] = tag 3313 if parent is not None: 3314 query["parent"] = parent 3315 if source_scope is not None: 3316 query["source_scope"] = source_scope 3317 if source_type is not None: 3318 query["source_type"] = source_type 3319 if source_id is not None: 3320 query["source_id"] = source_id 3321 if epic is not None: 3322 query["epic"] = epic 3323 if limit is not None: 3324 query["limit"] = limit 3325 if after_cursor is not None: 3326 query["after_cursor"] = after_cursor 3327 return await self._http.request( 3328 f"/api/v1/orgs/{org}/tasks/search", 3329 query=query, 3330 response_type=OrgTaskSearchResponse, 3331 )
Search an organization's tasks
Performs a full-text search over org-owned tasks for the specified
organization and returns matching results. Combine q with the optional
filters to narrow the result set further. When no query is provided, the
endpoint behaves like a filtered list.
The query field in the response echoes the effective search query.
Explicitly personal, team, or agent tasks are excluded here.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - q: Full-text search query matched against task names and descriptions. Takes precedence over
querywhen both are provided. - query: Alias for
q. Useqwhen possible; this parameter exists for compatibility. - status: Filter results by status. One of
"open","in_progress","in_review", or"done". Omit to include all statuses. - owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (
usr_...). - owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (
agi_...). - priority: Filter tasks by priority, from 0 (highest) to 4 (lowest).
- tag: Return only tasks carrying this tag (matched against the canonical lowercase form).
- parent: Return only subtasks of the given task (
tsk_...), or passnoneto return only top-level tasks. - source_scope: Return only tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters.
- source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters.
- epic: Return only tasks with this exact epic label.
- limit: Maximum number of tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
class
AsyncOrgThreadResource:
3334class AsyncOrgThreadResource: 3335 def __init__(self, http: HttpClient): 3336 self._http = http 3337 3338 async def list(self, org: str, *, key: str | None = None) -> OrgThreadListResponse: 3339 """ 3340 List organization-visibility threads 3341 Returns org-visibility threads for the specified organization. Every member 3342 of the organization can list these threads; they require no team membership. 3343 App-scoped developer tokens for the organization's app can list them too. 3344 3345 Args: 3346 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3347 key: Optional exact thread key, for example `support-room`. 3348 3349 Returns: 3350 Successful response 3351 """ 3352 query: dict[str, object] = {} 3353 if key is not None: 3354 query["key"] = key 3355 return await self._http.request( 3356 f"/api/v1/orgs/{org}/threads", 3357 query=query, 3358 response_type=OrgThreadListResponse, 3359 ) 3360 3361 async def create(self, org: str, input: OrgThreadCreateInput) -> Thread: 3362 """ 3363 Create an organization-visibility thread 3364 Creates a thread owned by the organization rather than a team, user, or agent. 3365 Every member of the organization can read and post without joining. The 3366 authenticated caller must be an organization administrator, or use an 3367 app-scoped developer token for the organization's app. 3368 When `thread.key` is supplied, creation is idempotent: a second call with the 3369 same key returns the existing org-visibility thread instead of inserting a 3370 duplicate. 3371 3372 Args: 3373 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3374 input: Request body. 3375 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3376 input.thread: Attributes for the new thread. Visibility is forced to `org`. 3377 3378 Returns: 3379 The organization-visibility thread. 3380 """ 3381 return await self._http.request( 3382 f"/api/v1/orgs/{org}/threads", 3383 method="POST", 3384 body=input, 3385 response_type=Thread, 3386 )
AsyncOrgThreadResource(http: archastro.platform.runtime.http_client.HttpClient)
3338 async def list(self, org: str, *, key: str | None = None) -> OrgThreadListResponse: 3339 """ 3340 List organization-visibility threads 3341 Returns org-visibility threads for the specified organization. Every member 3342 of the organization can list these threads; they require no team membership. 3343 App-scoped developer tokens for the organization's app can list them too. 3344 3345 Args: 3346 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3347 key: Optional exact thread key, for example `support-room`. 3348 3349 Returns: 3350 Successful response 3351 """ 3352 query: dict[str, object] = {} 3353 if key is not None: 3354 query["key"] = key 3355 return await self._http.request( 3356 f"/api/v1/orgs/{org}/threads", 3357 query=query, 3358 response_type=OrgThreadListResponse, 3359 )
List organization-visibility threads Returns org-visibility threads for the specified organization. Every member of the organization can list these threads; they require no team membership. App-scoped developer tokens for the organization's app can list them too.
Arguments:
- org: Organization ID (
org_...) whose org-visibility threads should be listed. - key: Optional exact thread key, for example
support-room.
Returns:
Successful response
async def
create( self, org: str, input: OrgThreadCreateInput) -> archastro.platform.types.threads.Thread:
3361 async def create(self, org: str, input: OrgThreadCreateInput) -> Thread: 3362 """ 3363 Create an organization-visibility thread 3364 Creates a thread owned by the organization rather than a team, user, or agent. 3365 Every member of the organization can read and post without joining. The 3366 authenticated caller must be an organization administrator, or use an 3367 app-scoped developer token for the organization's app. 3368 When `thread.key` is supplied, creation is idempotent: a second call with the 3369 same key returns the existing org-visibility thread instead of inserting a 3370 duplicate. 3371 3372 Args: 3373 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3374 input: Request body. 3375 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3376 input.thread: Attributes for the new thread. Visibility is forced to `org`. 3377 3378 Returns: 3379 The organization-visibility thread. 3380 """ 3381 return await self._http.request( 3382 f"/api/v1/orgs/{org}/threads", 3383 method="POST", 3384 body=input, 3385 response_type=Thread, 3386 )
Create an organization-visibility thread
Creates a thread owned by the organization rather than a team, user, or agent.
Every member of the organization can read and post without joining. The
authenticated caller must be an organization administrator, or use an
app-scoped developer token for the organization's app.
When thread.key is supplied, creation is idempotent: a second call with the
same key returns the existing org-visibility thread instead of inserting a
duplicate.
Arguments:
- org: Organization ID (
org_...) whose org-visibility threads should be listed. - input: Request body.
- input.skip_welcome_message: When
true, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults tofalse. - input.thread: Attributes for the new thread. Visibility is forced to
org.
Returns:
The organization-visibility thread.
class
AsyncOrgResource:
3389class AsyncOrgResource: 3390 def __init__(self, http: HttpClient): 3391 self._http = http 3392 self.tasks = AsyncOrgTaskResource(http) 3393 self.threads = AsyncOrgThreadResource(http) 3394 3395 async def list( 3396 self, *, search: str | None = None, page: int | None = None, page_size: int | None = None 3397 ) -> OrgListResponse: 3398 """ 3399 Search organizations 3400 Returns a paginated list of organizations within the authenticated app scope, 3401 optionally filtered by a free-text search term matched against name, slug, and 3402 domain (case-insensitive). Results are ordered by relevance when a search term 3403 is provided, and by creation time descending otherwise. 3404 The response includes only public-facing organization fields: ID, name, domain, 3405 and logo. Use the developer-scoped org endpoints to access full organization 3406 records. 3407 Pagination is offset-based. Pass `page` and `page_size` to navigate through 3408 results. The `has_next` and `has_prev` fields indicate whether adjacent pages 3409 exist. 3410 3411 Args: 3412 search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app. 3413 page: Page number to retrieve, starting at `1`. Defaults to `1` when omitted. 3414 page_size: Number of organizations to return per page. Defaults to `25`; maximum is `100`. 3415 3416 Returns: 3417 Successful response 3418 """ 3419 query: dict[str, object] = {} 3420 if search is not None: 3421 query["search"] = search 3422 if page is not None: 3423 query["page"] = page 3424 if page_size is not None: 3425 query["page_size"] = page_size 3426 return await self._http.request("/api/v1/orgs", query=query, response_type=OrgListResponse) 3427 3428 async def artifacts( 3429 self, 3430 org: str, 3431 *, 3432 limit: int | None = None, 3433 after_cursor: str | None = None, 3434 group_key: str | None = None, 3435 group_key_prefix: str | None = None, 3436 ) -> OrgArtifactsResponse: 3437 """ 3438 List completed organization artifacts 3439 Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded. 3440 3441 Args: 3442 org: Organization ID. 3443 limit: Maximum snapshots returned, from 1 to 100. 3444 after_cursor: Opaque cursor for the next page of older snapshots. 3445 group_key: Exact, case-sensitive grouping key. 3446 group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key. 3447 3448 Returns: 3449 Successful response 3450 """ 3451 query: dict[str, object] = {} 3452 if limit is not None: 3453 query["limit"] = limit 3454 if after_cursor is not None: 3455 query["after_cursor"] = after_cursor 3456 if group_key is not None: 3457 query["group_key"] = group_key 3458 if group_key_prefix is not None: 3459 query["group_key_prefix"] = group_key_prefix 3460 return await self._http.request( 3461 f"/api/v1/orgs/{org}/artifacts", 3462 query=query, 3463 response_type=OrgArtifactsResponse, 3464 ) 3465 3466 async def linked_accounts( 3467 self, 3468 org: str, 3469 *, 3470 user: builtins.list[str] | None = None, 3471 limit: int | None = None, 3472 after_cursor: str | None = None, 3473 ) -> OrgLinkedAccountsResponse: 3474 """ 3475 List an organization's linked accounts 3476 Returns the GitHub login each user in the organization signed in with, so 3477 clients can tell that a pull request's author and a Platform user are the 3478 same person. Users who never signed in with GitHub are absent. Any viewer 3479 acting within the organization can list them; other viewers get 404. 3480 Pass `user` to look up specific users instead of listing the whole 3481 organization. Results are ordered by user and paginated forward with 3482 `after_cursor`. 3483 3484 Args: 3485 org: Organization ID (`org_...`) whose linked accounts should be listed. 3486 user: Up to 100 user IDs (`usr_...`) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. 3487 limit: Maximum accounts returned, from 1 to 100. 3488 after_cursor: Opaque cursor for the next page. 3489 3490 Returns: 3491 Successful response 3492 """ 3493 query: dict[str, object] = {} 3494 if user is not None: 3495 query["user"] = user 3496 if limit is not None: 3497 query["limit"] = limit 3498 if after_cursor is not None: 3499 query["after_cursor"] = after_cursor 3500 return await self._http.request( 3501 f"/api/v1/orgs/{org}/linked_accounts", 3502 query=query, 3503 response_type=OrgLinkedAccountsResponse, 3504 ) 3505 3506 async def task_epics( 3507 self, 3508 org: str, 3509 *, 3510 source_scope: str | None = None, 3511 source_type: str | None = None, 3512 source_id: str | None = None, 3513 top_priority: int | None = None, 3514 include_closed: bool | None = None, 3515 limit: int | None = None, 3516 after_cursor: str | None = None, 3517 ) -> OrgTaskEpicsResponse: 3518 """ 3519 List an organization's epic summaries 3520 Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 3521 3522 Args: 3523 org: Organization ID (`org_...`) owning the tasks. 3524 source_scope: Exact source scope; supply all three source fields. 3525 source_type: Exact source type. 3526 source_id: Exact source ID. 3527 top_priority: Exact highest open priority, from 0 to 4. 3528 include_closed: Include epics with no non-closed tasks; defaults to false. 3529 limit: Maximum epics; defaults to 50, capped at 100. 3530 after_cursor: Opaque forward cursor from the preceding page. 3531 3532 Returns: 3533 Successful response 3534 """ 3535 query: dict[str, object] = {} 3536 if source_scope is not None: 3537 query["source_scope"] = source_scope 3538 if source_type is not None: 3539 query["source_type"] = source_type 3540 if source_id is not None: 3541 query["source_id"] = source_id 3542 if top_priority is not None: 3543 query["top_priority"] = top_priority 3544 if include_closed is not None: 3545 query["include_closed"] = include_closed 3546 if limit is not None: 3547 query["limit"] = limit 3548 if after_cursor is not None: 3549 query["after_cursor"] = after_cursor 3550 return await self._http.request( 3551 f"/api/v1/orgs/{org}/task_epics", 3552 query=query, 3553 response_type=OrgTaskEpicsResponse, 3554 )
AsyncOrgResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, *, search: str | None = None, page: int | None = None, page_size: int | None = None) -> OrgListResponse:
3395 async def list( 3396 self, *, search: str | None = None, page: int | None = None, page_size: int | None = None 3397 ) -> OrgListResponse: 3398 """ 3399 Search organizations 3400 Returns a paginated list of organizations within the authenticated app scope, 3401 optionally filtered by a free-text search term matched against name, slug, and 3402 domain (case-insensitive). Results are ordered by relevance when a search term 3403 is provided, and by creation time descending otherwise. 3404 The response includes only public-facing organization fields: ID, name, domain, 3405 and logo. Use the developer-scoped org endpoints to access full organization 3406 records. 3407 Pagination is offset-based. Pass `page` and `page_size` to navigate through 3408 results. The `has_next` and `has_prev` fields indicate whether adjacent pages 3409 exist. 3410 3411 Args: 3412 search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app. 3413 page: Page number to retrieve, starting at `1`. Defaults to `1` when omitted. 3414 page_size: Number of organizations to return per page. Defaults to `25`; maximum is `100`. 3415 3416 Returns: 3417 Successful response 3418 """ 3419 query: dict[str, object] = {} 3420 if search is not None: 3421 query["search"] = search 3422 if page is not None: 3423 query["page"] = page 3424 if page_size is not None: 3425 query["page_size"] = page_size 3426 return await self._http.request("/api/v1/orgs", query=query, response_type=OrgListResponse)
Search organizations
Returns a paginated list of organizations within the authenticated app scope,
optionally filtered by a free-text search term matched against name, slug, and
domain (case-insensitive). Results are ordered by relevance when a search term
is provided, and by creation time descending otherwise.
The response includes only public-facing organization fields: ID, name, domain,
and logo. Use the developer-scoped org endpoints to access full organization
records.
Pagination is offset-based. Pass page and page_size to navigate through
results. The has_next and has_prev fields indicate whether adjacent pages
exist.
Arguments:
- search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app.
- page: Page number to retrieve, starting at
1. Defaults to1when omitted. - page_size: Number of organizations to return per page. Defaults to
25; maximum is100.
Returns:
Successful response
async def
artifacts( self, org: str, *, limit: int | None = None, after_cursor: str | None = None, group_key: str | None = None, group_key_prefix: str | None = None) -> OrgArtifactsResponse:
3428 async def artifacts( 3429 self, 3430 org: str, 3431 *, 3432 limit: int | None = None, 3433 after_cursor: str | None = None, 3434 group_key: str | None = None, 3435 group_key_prefix: str | None = None, 3436 ) -> OrgArtifactsResponse: 3437 """ 3438 List completed organization artifacts 3439 Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded. 3440 3441 Args: 3442 org: Organization ID. 3443 limit: Maximum snapshots returned, from 1 to 100. 3444 after_cursor: Opaque cursor for the next page of older snapshots. 3445 group_key: Exact, case-sensitive grouping key. 3446 group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key. 3447 3448 Returns: 3449 Successful response 3450 """ 3451 query: dict[str, object] = {} 3452 if limit is not None: 3453 query["limit"] = limit 3454 if after_cursor is not None: 3455 query["after_cursor"] = after_cursor 3456 if group_key is not None: 3457 query["group_key"] = group_key 3458 if group_key_prefix is not None: 3459 query["group_key_prefix"] = group_key_prefix 3460 return await self._http.request( 3461 f"/api/v1/orgs/{org}/artifacts", 3462 query=query, 3463 response_type=OrgArtifactsResponse, 3464 )
List completed organization artifacts Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded.
Arguments:
- org: Organization ID.
- limit: Maximum snapshots returned, from 1 to 100.
- after_cursor: Opaque cursor for the next page of older snapshots.
- group_key: Exact, case-sensitive grouping key.
- group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key.
Returns:
Successful response
async def
linked_accounts( self, org: str, *, user: list[str] | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgLinkedAccountsResponse:
3466 async def linked_accounts( 3467 self, 3468 org: str, 3469 *, 3470 user: builtins.list[str] | None = None, 3471 limit: int | None = None, 3472 after_cursor: str | None = None, 3473 ) -> OrgLinkedAccountsResponse: 3474 """ 3475 List an organization's linked accounts 3476 Returns the GitHub login each user in the organization signed in with, so 3477 clients can tell that a pull request's author and a Platform user are the 3478 same person. Users who never signed in with GitHub are absent. Any viewer 3479 acting within the organization can list them; other viewers get 404. 3480 Pass `user` to look up specific users instead of listing the whole 3481 organization. Results are ordered by user and paginated forward with 3482 `after_cursor`. 3483 3484 Args: 3485 org: Organization ID (`org_...`) whose linked accounts should be listed. 3486 user: Up to 100 user IDs (`usr_...`) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. 3487 limit: Maximum accounts returned, from 1 to 100. 3488 after_cursor: Opaque cursor for the next page. 3489 3490 Returns: 3491 Successful response 3492 """ 3493 query: dict[str, object] = {} 3494 if user is not None: 3495 query["user"] = user 3496 if limit is not None: 3497 query["limit"] = limit 3498 if after_cursor is not None: 3499 query["after_cursor"] = after_cursor 3500 return await self._http.request( 3501 f"/api/v1/orgs/{org}/linked_accounts", 3502 query=query, 3503 response_type=OrgLinkedAccountsResponse, 3504 )
List an organization's linked accounts
Returns the GitHub login each user in the organization signed in with, so
clients can tell that a pull request's author and a Platform user are the
same person. Users who never signed in with GitHub are absent. Any viewer
acting within the organization can list them; other viewers get 404.
Pass user to look up specific users instead of listing the whole
organization. Results are ordered by user and paginated forward with
after_cursor.
Arguments:
- org: Organization ID (
org_...) whose linked accounts should be listed. - user: Up to 100 user IDs (
usr_...) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. - limit: Maximum accounts returned, from 1 to 100.
- after_cursor: Opaque cursor for the next page.
Returns:
Successful response
async def
task_epics( self, org: str, *, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, top_priority: int | None = None, include_closed: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskEpicsResponse:
3506 async def task_epics( 3507 self, 3508 org: str, 3509 *, 3510 source_scope: str | None = None, 3511 source_type: str | None = None, 3512 source_id: str | None = None, 3513 top_priority: int | None = None, 3514 include_closed: bool | None = None, 3515 limit: int | None = None, 3516 after_cursor: str | None = None, 3517 ) -> OrgTaskEpicsResponse: 3518 """ 3519 List an organization's epic summaries 3520 Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 3521 3522 Args: 3523 org: Organization ID (`org_...`) owning the tasks. 3524 source_scope: Exact source scope; supply all three source fields. 3525 source_type: Exact source type. 3526 source_id: Exact source ID. 3527 top_priority: Exact highest open priority, from 0 to 4. 3528 include_closed: Include epics with no non-closed tasks; defaults to false. 3529 limit: Maximum epics; defaults to 50, capped at 100. 3530 after_cursor: Opaque forward cursor from the preceding page. 3531 3532 Returns: 3533 Successful response 3534 """ 3535 query: dict[str, object] = {} 3536 if source_scope is not None: 3537 query["source_scope"] = source_scope 3538 if source_type is not None: 3539 query["source_type"] = source_type 3540 if source_id is not None: 3541 query["source_id"] = source_id 3542 if top_priority is not None: 3543 query["top_priority"] = top_priority 3544 if include_closed is not None: 3545 query["include_closed"] = include_closed 3546 if limit is not None: 3547 query["limit"] = limit 3548 if after_cursor is not None: 3549 query["after_cursor"] = after_cursor 3550 return await self._http.request( 3551 f"/api/v1/orgs/{org}/task_epics", 3552 query=query, 3553 response_type=OrgTaskEpicsResponse, 3554 )
List an organization's epic summaries Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created.
Arguments:
- org: Organization ID (
org_...) owning the tasks. - source_scope: Exact source scope; supply all three source fields.
- source_type: Exact source type.
- source_id: Exact source ID.
- top_priority: Exact highest open priority, from 0 to 4.
- include_closed: Include epics with no non-closed tasks; defaults to false.
- limit: Maximum epics; defaults to 50, capped at 100.
- after_cursor: Opaque forward cursor from the preceding page.
Returns:
Successful response
class
OrgTaskResource:
3557class OrgTaskResource: 3558 def __init__(self, http: SyncHttpClient): 3559 self._http = http 3560 3561 def list( 3562 self, 3563 org: str, 3564 *, 3565 status: str | None = None, 3566 owner_user: str | None = None, 3567 owner_agent: str | None = None, 3568 priority: int | None = None, 3569 tag: str | None = None, 3570 parent: str | None = None, 3571 source_scope: str | None = None, 3572 source_type: str | None = None, 3573 source_id: str | None = None, 3574 epic: str | None = None, 3575 search: str | None = None, 3576 sort: str | None = None, 3577 order: str | None = None, 3578 due_before: str | None = None, 3579 due_after: str | None = None, 3580 overdue: bool | None = None, 3581 ready: bool | None = None, 3582 attention: bool | None = None, 3583 limit: int | None = None, 3584 after_cursor: str | None = None, 3585 ) -> OrgTaskListResponse: 3586 """ 3587 List an organization's tasks 3588 Returns org-owned tasks for the specified organization: rows with the org 3589 tenant and no narrower user/team/agent scope. Explicitly personal, team, or 3590 agent tasks are excluded here; list those via the user/team collections or 3591 fetch them directly when authorized. 3592 Every organization member may list. App-scoped developer and 3593 server-to-server callers supply the org in the route. 3594 3595 Args: 3596 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3597 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3598 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3599 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3600 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3601 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3602 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3603 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3604 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3605 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3606 epic: Return only tasks with this exact epic label. 3607 search: Restrict results to tasks whose name or description contains this string. 3608 sort: Sort key. One of `"created"` (default most recently created first), `"due_date"` (soonest due first; tasks without a due date always sort last), or `"priority"` (most urgent first). Ties break by most recently created. 3609 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3610 due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. 3611 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3612 overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. 3613 ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. 3614 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3615 limit: Maximum number of tasks to return. Capped at 100. 3616 after_cursor: Opaque cursor returned by the previous page. 3617 3618 Returns: 3619 Successful response 3620 """ 3621 query: dict[str, object] = {} 3622 if status is not None: 3623 query["status"] = status 3624 if owner_user is not None: 3625 query["owner_user"] = owner_user 3626 if owner_agent is not None: 3627 query["owner_agent"] = owner_agent 3628 if priority is not None: 3629 query["priority"] = priority 3630 if tag is not None: 3631 query["tag"] = tag 3632 if parent is not None: 3633 query["parent"] = parent 3634 if source_scope is not None: 3635 query["source_scope"] = source_scope 3636 if source_type is not None: 3637 query["source_type"] = source_type 3638 if source_id is not None: 3639 query["source_id"] = source_id 3640 if epic is not None: 3641 query["epic"] = epic 3642 if search is not None: 3643 query["search"] = search 3644 if sort is not None: 3645 query["sort"] = sort 3646 if order is not None: 3647 query["order"] = order 3648 if due_before is not None: 3649 query["due_before"] = due_before 3650 if due_after is not None: 3651 query["due_after"] = due_after 3652 if overdue is not None: 3653 query["overdue"] = overdue 3654 if ready is not None: 3655 query["ready"] = ready 3656 if attention is not None: 3657 query["attention"] = attention 3658 if limit is not None: 3659 query["limit"] = limit 3660 if after_cursor is not None: 3661 query["after_cursor"] = after_cursor 3662 return self._http.request( 3663 f"/api/v1/orgs/{org}/tasks", 3664 query=query, 3665 response_type=OrgTaskListResponse, 3666 ) 3667 3668 def create(self, org: str, input: OrgTaskCreateInput) -> Task: 3669 """ 3670 Create a task for an organization 3671 Creates a new org-owned task (org tenant, no narrower user/team/agent 3672 scope) and returns the full task object. User-authenticated calls are 3673 attributed to the authenticated user or agent. App-scoped developer and 3674 server-to-server callers must provide an explicit `user` or `agent` actor 3675 for the organization. Every referenced principal is validated against the 3676 app and organization before creation. 3677 3678 Args: 3679 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3680 input: Request body. 3681 input.agent: Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization. 3682 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3683 input.user: Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`. 3684 3685 Returns: 3686 The newly created task. 3687 """ 3688 return self._http.request( 3689 f"/api/v1/orgs/{org}/tasks", 3690 method="POST", 3691 body=input, 3692 response_type=Task, 3693 ) 3694 3695 def blocker_cycles( 3696 self, org: str, *, limit: int | None = None, after_cursor: str | None = None 3697 ) -> OrgTaskBlockerCyclesResponse: 3698 """ 3699 List task blocker cycles for an organization 3700 Runs an on-demand diagnostic over unfinished org-owned tasks for the 3701 specified organization and returns a forward cursor-paginated page of 3702 complete cyclic blocker components. Detection is bounded to owners with at 3703 most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent 3704 task updates, lease acquisition, or completion. 3705 3706 Args: 3707 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3708 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3709 after_cursor: Opaque cursor returned by the preceding page. 3710 3711 Returns: 3712 Successful response 3713 """ 3714 query: dict[str, object] = {} 3715 if limit is not None: 3716 query["limit"] = limit 3717 if after_cursor is not None: 3718 query["after_cursor"] = after_cursor 3719 return self._http.request( 3720 f"/api/v1/orgs/{org}/tasks/blocker_cycles", 3721 query=query, 3722 response_type=OrgTaskBlockerCyclesResponse, 3723 ) 3724 3725 def by_source(self, org: str, input: OrgTaskBySourceInput) -> TaskEnsureResult: 3726 """ 3727 Find or create a task by source 3728 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3729 3730 Args: 3731 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3732 input: Request body. 3733 input.agent: Explicit acting agent for privileged callers. 3734 input.description: Initial task description. 3735 input.epic: Initial epic grouping. 3736 input.name: Initial task name. 3737 input.source_id: Source identity, for example owner/repo#123. 3738 input.source_scope: Source scope, for example github. 3739 input.source_type: Source type, for example pull_request. 3740 input.status: Initial task status. 3741 input.team: Team owner. 3742 input.user: User owner, or explicit acting user on a team route. 3743 3744 Returns: 3745 The task and whether this request created it. 3746 """ 3747 return self._http.request( 3748 f"/api/v1/orgs/{org}/tasks/by-source", 3749 method="PUT", 3750 body=input, 3751 response_type=TaskEnsureResult, 3752 ) 3753 3754 def metrics(self, org: str, *, days: int | None = None) -> OrgTaskMetricsResponse: 3755 """ 3756 Get task activity metrics for an organization 3757 Returns task activity metrics scoped to org-owned tasks (org tenant, no 3758 narrower user/team/agent scope). `open` counts currently open or 3759 in-progress org tasks, `created` counts tasks inserted in the UTC-day 3760 window, and `completed` counts tasks whose `closed_at` falls in that window 3761 while still in a closed status. Hard-deleted tasks are absent from the 3762 projection and therefore omitted. The daily series is zero-filled across 3763 the requested window and includes reconstructed end-of-day `open` stock. 3764 Any organization member may read this count-only summary. Requests from 3765 callers without org access return 404 so organization existence is not 3766 disclosed. 3767 3768 Args: 3769 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3770 days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30. 3771 3772 Returns: 3773 Successful response 3774 """ 3775 query: dict[str, object] = {} 3776 if days is not None: 3777 query["days"] = days 3778 return self._http.request( 3779 f"/api/v1/orgs/{org}/tasks/metrics", 3780 query=query, 3781 response_type=OrgTaskMetricsResponse, 3782 ) 3783 3784 def ready( 3785 self, 3786 org: str, 3787 *, 3788 explain: bool | None = None, 3789 assigned_to_me: bool | None = None, 3790 source_scope: str | None = None, 3791 source_type: str | None = None, 3792 source_id: str | None = None, 3793 epic: str | None = None, 3794 limit: int | None = None, 3795 after_cursor: str | None = None, 3796 ) -> OrgTaskReadyResponse: 3797 """ 3798 List an organization's ready tasks 3799 Returns open org-owned tasks with no unfinished blockers and no active 3800 session lease. Readiness is calculated by the server from the current task 3801 projection. It is a snapshot, not a reservation; claim a task lease before 3802 starting work. 3803 Results are ordered by priority (0, the most urgent, first), then oldest 3804 first, so the first page is always the most urgent ready work. 3805 Pass `explain=true` to include every open task with a stable readiness reason. 3806 3807 Args: 3808 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3809 explain: Include blocked and actively leased open tasks with exclusion reasons. 3810 assigned_to_me: Only include tasks assigned to the authenticated user. 3811 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3812 source_type: Only include tasks whose source matches this object kind. 3813 source_id: Only include tasks whose source matches this object identity. 3814 epic: Only include tasks with this exact epic label. 3815 limit: Maximum number of readiness entries to return. Capped at 100. 3816 after_cursor: Opaque cursor returned by the previous page. 3817 3818 Returns: 3819 Successful response 3820 """ 3821 query: dict[str, object] = {} 3822 if explain is not None: 3823 query["explain"] = explain 3824 if assigned_to_me is not None: 3825 query["assigned_to_me"] = assigned_to_me 3826 if source_scope is not None: 3827 query["source_scope"] = source_scope 3828 if source_type is not None: 3829 query["source_type"] = source_type 3830 if source_id is not None: 3831 query["source_id"] = source_id 3832 if epic is not None: 3833 query["epic"] = epic 3834 if limit is not None: 3835 query["limit"] = limit 3836 if after_cursor is not None: 3837 query["after_cursor"] = after_cursor 3838 return self._http.request( 3839 f"/api/v1/orgs/{org}/tasks/ready", 3840 query=query, 3841 response_type=OrgTaskReadyResponse, 3842 ) 3843 3844 def search( 3845 self, 3846 org: str, 3847 *, 3848 q: str | None = None, 3849 query: str | None = None, 3850 status: str | None = None, 3851 owner_user: str | None = None, 3852 owner_agent: str | None = None, 3853 priority: int | None = None, 3854 tag: str | None = None, 3855 parent: str | None = None, 3856 source_scope: str | None = None, 3857 source_type: str | None = None, 3858 source_id: str | None = None, 3859 epic: str | None = None, 3860 limit: int | None = None, 3861 after_cursor: str | None = None, 3862 ) -> OrgTaskSearchResponse: 3863 """ 3864 Search an organization's tasks 3865 Performs a full-text search over org-owned tasks for the specified 3866 organization and returns matching results. Combine `q` with the optional 3867 filters to narrow the result set further. When no query is provided, the 3868 endpoint behaves like a filtered list. 3869 The `query` field in the response echoes the effective search query. 3870 Explicitly personal, team, or agent tasks are excluded here. 3871 3872 Args: 3873 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3874 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3875 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3876 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3877 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3878 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3879 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3880 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3881 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3882 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3883 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3884 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3885 epic: Return only tasks with this exact epic label. 3886 limit: Maximum number of tasks to return. Capped at 100. 3887 after_cursor: Opaque cursor returned by the previous page. 3888 3889 Returns: 3890 Successful response 3891 """ 3892 query: dict[str, object] = {} 3893 if q is not None: 3894 query["q"] = q 3895 if query is not None: 3896 query["query"] = query 3897 if status is not None: 3898 query["status"] = status 3899 if owner_user is not None: 3900 query["owner_user"] = owner_user 3901 if owner_agent is not None: 3902 query["owner_agent"] = owner_agent 3903 if priority is not None: 3904 query["priority"] = priority 3905 if tag is not None: 3906 query["tag"] = tag 3907 if parent is not None: 3908 query["parent"] = parent 3909 if source_scope is not None: 3910 query["source_scope"] = source_scope 3911 if source_type is not None: 3912 query["source_type"] = source_type 3913 if source_id is not None: 3914 query["source_id"] = source_id 3915 if epic is not None: 3916 query["epic"] = epic 3917 if limit is not None: 3918 query["limit"] = limit 3919 if after_cursor is not None: 3920 query["after_cursor"] = after_cursor 3921 return self._http.request( 3922 f"/api/v1/orgs/{org}/tasks/search", 3923 query=query, 3924 response_type=OrgTaskSearchResponse, 3925 )
OrgTaskResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, org: str, *, status: str | None = None, owner_user: str | None = None, owner_agent: str | None = None, priority: int | None = None, tag: str | None = None, parent: str | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, epic: str | None = None, search: str | None = None, sort: str | None = None, order: str | None = None, due_before: str | None = None, due_after: str | None = None, overdue: bool | None = None, ready: bool | None = None, attention: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskListResponse:
3561 def list( 3562 self, 3563 org: str, 3564 *, 3565 status: str | None = None, 3566 owner_user: str | None = None, 3567 owner_agent: str | None = None, 3568 priority: int | None = None, 3569 tag: str | None = None, 3570 parent: str | None = None, 3571 source_scope: str | None = None, 3572 source_type: str | None = None, 3573 source_id: str | None = None, 3574 epic: str | None = None, 3575 search: str | None = None, 3576 sort: str | None = None, 3577 order: str | None = None, 3578 due_before: str | None = None, 3579 due_after: str | None = None, 3580 overdue: bool | None = None, 3581 ready: bool | None = None, 3582 attention: bool | None = None, 3583 limit: int | None = None, 3584 after_cursor: str | None = None, 3585 ) -> OrgTaskListResponse: 3586 """ 3587 List an organization's tasks 3588 Returns org-owned tasks for the specified organization: rows with the org 3589 tenant and no narrower user/team/agent scope. Explicitly personal, team, or 3590 agent tasks are excluded here; list those via the user/team collections or 3591 fetch them directly when authorized. 3592 Every organization member may list. App-scoped developer and 3593 server-to-server callers supply the org in the route. 3594 3595 Args: 3596 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3597 status: Filter tasks by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to return tasks in all statuses. 3598 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3599 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3600 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3601 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3602 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3603 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3604 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3605 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3606 epic: Return only tasks with this exact epic label. 3607 search: Restrict results to tasks whose name or description contains this string. 3608 sort: Sort key. One of `"created"` (default most recently created first), `"due_date"` (soonest due first; tasks without a due date always sort last), or `"priority"` (most urgent first). Ties break by most recently created. 3609 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3610 due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (`2026-08-01T00:00:00Z`) or date (`2026-08-01`, meaning midnight UTC). Tasks without a due date are excluded. 3611 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3612 overdue: When `true`, return only overdue tasks: a due date before the current UTC day and a status other than `"done"`. A task due today is not overdue. 3613 ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work. 3614 attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry. 3615 limit: Maximum number of tasks to return. Capped at 100. 3616 after_cursor: Opaque cursor returned by the previous page. 3617 3618 Returns: 3619 Successful response 3620 """ 3621 query: dict[str, object] = {} 3622 if status is not None: 3623 query["status"] = status 3624 if owner_user is not None: 3625 query["owner_user"] = owner_user 3626 if owner_agent is not None: 3627 query["owner_agent"] = owner_agent 3628 if priority is not None: 3629 query["priority"] = priority 3630 if tag is not None: 3631 query["tag"] = tag 3632 if parent is not None: 3633 query["parent"] = parent 3634 if source_scope is not None: 3635 query["source_scope"] = source_scope 3636 if source_type is not None: 3637 query["source_type"] = source_type 3638 if source_id is not None: 3639 query["source_id"] = source_id 3640 if epic is not None: 3641 query["epic"] = epic 3642 if search is not None: 3643 query["search"] = search 3644 if sort is not None: 3645 query["sort"] = sort 3646 if order is not None: 3647 query["order"] = order 3648 if due_before is not None: 3649 query["due_before"] = due_before 3650 if due_after is not None: 3651 query["due_after"] = due_after 3652 if overdue is not None: 3653 query["overdue"] = overdue 3654 if ready is not None: 3655 query["ready"] = ready 3656 if attention is not None: 3657 query["attention"] = attention 3658 if limit is not None: 3659 query["limit"] = limit 3660 if after_cursor is not None: 3661 query["after_cursor"] = after_cursor 3662 return self._http.request( 3663 f"/api/v1/orgs/{org}/tasks", 3664 query=query, 3665 response_type=OrgTaskListResponse, 3666 )
List an organization's tasks Returns org-owned tasks for the specified organization: rows with the org tenant and no narrower user/team/agent scope. Explicitly personal, team, or agent tasks are excluded here; list those via the user/team collections or fetch them directly when authorized. Every organization member may list. App-scoped developer and server-to-server callers supply the org in the route.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - status: Filter tasks by status. One of
"open","in_progress","in_review", or"done". Omit to return tasks in all statuses. - owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (
usr_...). - owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (
agi_...). - priority: Filter tasks by priority, from 0 (highest) to 4 (lowest).
- tag: Return only tasks carrying this tag (matched against the canonical lowercase form).
- parent: Return only subtasks of the given task (
tsk_...), or passnoneto return only top-level tasks. - source_scope: Return only tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters.
- source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters.
- epic: Return only tasks with this exact epic label.
- search: Restrict results to tasks whose name or description contains this string.
- sort: Sort key. One of
"created"(default most recently created first),"due_date"(soonest due first; tasks without a due date always sort last), or"priority"(most urgent first). Ties break by most recently created. - order: Sort direction,
"asc"or"desc". Defaults to"desc"forcreatedand"asc"fordue_dateandpriority. - due_before: Return only tasks with a due date strictly before this ISO 8601 datetime (
2026-08-01T00:00:00Z) or date (2026-08-01, meaning midnight UTC). Tasks without a due date are excluded. - due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded.
- overdue: When
true, return only overdue tasks: a due date before the current UTC day and a status other than"done". A task due today is not overdue. - ready: When true, return only open tasks with no unfinished blockers and no active session lease. This is a projection snapshot; claim a lease before starting work.
- attention: When true, return paused, failed, or in-progress tasks with no lease or a past lease expiry.
- limit: Maximum number of tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
3668 def create(self, org: str, input: OrgTaskCreateInput) -> Task: 3669 """ 3670 Create a task for an organization 3671 Creates a new org-owned task (org tenant, no narrower user/team/agent 3672 scope) and returns the full task object. User-authenticated calls are 3673 attributed to the authenticated user or agent. App-scoped developer and 3674 server-to-server callers must provide an explicit `user` or `agent` actor 3675 for the organization. Every referenced principal is validated against the 3676 app and organization before creation. 3677 3678 Args: 3679 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3680 input: Request body. 3681 input.agent: Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the organization. 3682 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3683 input.user: Explicit acting user (`usr_...`) for a developer or server-to-server call. Mutually exclusive with an acting `agent`. 3684 3685 Returns: 3686 The newly created task. 3687 """ 3688 return self._http.request( 3689 f"/api/v1/orgs/{org}/tasks", 3690 method="POST", 3691 body=input, 3692 response_type=Task, 3693 )
Create a task for an organization
Creates a new org-owned task (org tenant, no narrower user/team/agent
scope) and returns the full task object. User-authenticated calls are
attributed to the authenticated user or agent. App-scoped developer and
server-to-server callers must provide an explicit user or agent actor
for the organization. Every referenced principal is validated against the
app and organization before creation.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - input: Request body.
- input.agent: Explicit acting agent (
agi_...) for a developer or server-to-server call. Mutually exclusive with an actinguser; the agent must belong to the organization. - input.task: Attributes for the task to create.
nameis required; all other fields are optional. - input.user: Explicit acting user (
usr_...) for a developer or server-to-server call. Mutually exclusive with an actingagent.
Returns:
The newly created task.
def
blocker_cycles( self, org: str, *, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskBlockerCyclesResponse:
3695 def blocker_cycles( 3696 self, org: str, *, limit: int | None = None, after_cursor: str | None = None 3697 ) -> OrgTaskBlockerCyclesResponse: 3698 """ 3699 List task blocker cycles for an organization 3700 Runs an on-demand diagnostic over unfinished org-owned tasks for the 3701 specified organization and returns a forward cursor-paginated page of 3702 complete cyclic blocker components. Detection is bounded to owners with at 3703 most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent 3704 task updates, lease acquisition, or completion. 3705 3706 Args: 3707 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3708 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3709 after_cursor: Opaque cursor returned by the preceding page. 3710 3711 Returns: 3712 Successful response 3713 """ 3714 query: dict[str, object] = {} 3715 if limit is not None: 3716 query["limit"] = limit 3717 if after_cursor is not None: 3718 query["after_cursor"] = after_cursor 3719 return self._http.request( 3720 f"/api/v1/orgs/{org}/tasks/blocker_cycles", 3721 query=query, 3722 response_type=OrgTaskBlockerCyclesResponse, 3723 )
List task blocker cycles for an organization Runs an on-demand diagnostic over unfinished org-owned tasks for the specified organization and returns a forward cursor-paginated page of complete cyclic blocker components. Detection is bounded to owners with at most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent task updates, lease acquisition, or completion.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - limit: Maximum cycle components to return. Defaults to 50; maximum is 100.
- after_cursor: Opaque cursor returned by the preceding page.
Returns:
Successful response
def
by_source( self, org: str, input: OrgTaskBySourceInput) -> archastro.platform.types.tasks.TaskEnsureResult:
3725 def by_source(self, org: str, input: OrgTaskBySourceInput) -> TaskEnsureResult: 3726 """ 3727 Find or create a task by source 3728 Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted. 3729 3730 Args: 3731 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3732 input: Request body. 3733 input.agent: Explicit acting agent for privileged callers. 3734 input.description: Initial task description. 3735 input.epic: Initial epic grouping. 3736 input.name: Initial task name. 3737 input.source_id: Source identity, for example owner/repo#123. 3738 input.source_scope: Source scope, for example github. 3739 input.source_type: Source type, for example pull_request. 3740 input.status: Initial task status. 3741 input.team: Team owner. 3742 input.user: User owner, or explicit acting user on a team route. 3743 3744 Returns: 3745 The task and whether this request created it. 3746 """ 3747 return self._http.request( 3748 f"/api/v1/orgs/{org}/tasks/by-source", 3749 method="PUT", 3750 body=input, 3751 response_type=TaskEnsureResult, 3752 )
Find or create a task by source Atomically creates one task per owner, tenant and source. Retries return the current task without updating it. Historical tasks created through ordinary create are not adopted.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - input: Request body.
- input.agent: Explicit acting agent for privileged callers.
- input.description: Initial task description.
- input.epic: Initial epic grouping.
- input.name: Initial task name.
- input.source_id: Source identity, for example owner/repo#123.
- input.source_scope: Source scope, for example github.
- input.source_type: Source type, for example pull_request.
- input.status: Initial task status.
- input.team: Team owner.
- input.user: User owner, or explicit acting user on a team route.
Returns:
The task and whether this request created it.
3754 def metrics(self, org: str, *, days: int | None = None) -> OrgTaskMetricsResponse: 3755 """ 3756 Get task activity metrics for an organization 3757 Returns task activity metrics scoped to org-owned tasks (org tenant, no 3758 narrower user/team/agent scope). `open` counts currently open or 3759 in-progress org tasks, `created` counts tasks inserted in the UTC-day 3760 window, and `completed` counts tasks whose `closed_at` falls in that window 3761 while still in a closed status. Hard-deleted tasks are absent from the 3762 projection and therefore omitted. The daily series is zero-filled across 3763 the requested window and includes reconstructed end-of-day `open` stock. 3764 Any organization member may read this count-only summary. Requests from 3765 callers without org access return 404 so organization existence is not 3766 disclosed. 3767 3768 Args: 3769 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3770 days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30. 3771 3772 Returns: 3773 Successful response 3774 """ 3775 query: dict[str, object] = {} 3776 if days is not None: 3777 query["days"] = days 3778 return self._http.request( 3779 f"/api/v1/orgs/{org}/tasks/metrics", 3780 query=query, 3781 response_type=OrgTaskMetricsResponse, 3782 )
Get task activity metrics for an organization
Returns task activity metrics scoped to org-owned tasks (org tenant, no
narrower user/team/agent scope). open counts currently open or
in-progress org tasks, created counts tasks inserted in the UTC-day
window, and completed counts tasks whose closed_at falls in that window
while still in a closed status. Hard-deleted tasks are absent from the
projection and therefore omitted. The daily series is zero-filled across
the requested window and includes reconstructed end-of-day open stock.
Any organization member may read this count-only summary. Requests from
callers without org access return 404 so organization existence is not
disclosed.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - days: UTC-day window. One of 7, 30, 90, or 365; defaults to 30.
Returns:
Successful response
def
ready( self, org: str, *, explain: bool | None = None, assigned_to_me: bool | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, epic: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskReadyResponse:
3784 def ready( 3785 self, 3786 org: str, 3787 *, 3788 explain: bool | None = None, 3789 assigned_to_me: bool | None = None, 3790 source_scope: str | None = None, 3791 source_type: str | None = None, 3792 source_id: str | None = None, 3793 epic: str | None = None, 3794 limit: int | None = None, 3795 after_cursor: str | None = None, 3796 ) -> OrgTaskReadyResponse: 3797 """ 3798 List an organization's ready tasks 3799 Returns open org-owned tasks with no unfinished blockers and no active 3800 session lease. Readiness is calculated by the server from the current task 3801 projection. It is a snapshot, not a reservation; claim a task lease before 3802 starting work. 3803 Results are ordered by priority (0, the most urgent, first), then oldest 3804 first, so the first page is always the most urgent ready work. 3805 Pass `explain=true` to include every open task with a stable readiness reason. 3806 3807 Args: 3808 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3809 explain: Include blocked and actively leased open tasks with exclusion reasons. 3810 assigned_to_me: Only include tasks assigned to the authenticated user. 3811 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3812 source_type: Only include tasks whose source matches this object kind. 3813 source_id: Only include tasks whose source matches this object identity. 3814 epic: Only include tasks with this exact epic label. 3815 limit: Maximum number of readiness entries to return. Capped at 100. 3816 after_cursor: Opaque cursor returned by the previous page. 3817 3818 Returns: 3819 Successful response 3820 """ 3821 query: dict[str, object] = {} 3822 if explain is not None: 3823 query["explain"] = explain 3824 if assigned_to_me is not None: 3825 query["assigned_to_me"] = assigned_to_me 3826 if source_scope is not None: 3827 query["source_scope"] = source_scope 3828 if source_type is not None: 3829 query["source_type"] = source_type 3830 if source_id is not None: 3831 query["source_id"] = source_id 3832 if epic is not None: 3833 query["epic"] = epic 3834 if limit is not None: 3835 query["limit"] = limit 3836 if after_cursor is not None: 3837 query["after_cursor"] = after_cursor 3838 return self._http.request( 3839 f"/api/v1/orgs/{org}/tasks/ready", 3840 query=query, 3841 response_type=OrgTaskReadyResponse, 3842 )
List an organization's ready tasks
Returns open org-owned tasks with no unfinished blockers and no active
session lease. Readiness is calculated by the server from the current task
projection. It is a snapshot, not a reservation; claim a task lease before
starting work.
Results are ordered by priority (0, the most urgent, first), then oldest
first, so the first page is always the most urgent ready work.
Pass explain=true to include every open task with a stable readiness reason.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - explain: Include blocked and actively leased open tasks with exclusion reasons.
- assigned_to_me: Only include tasks assigned to the authenticated user.
- source_scope: Only include tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Only include tasks whose source matches this object kind.
- source_id: Only include tasks whose source matches this object identity.
- epic: Only include tasks with this exact epic label.
- limit: Maximum number of readiness entries to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
def
search( self, org: str, *, q: str | None = None, query: str | None = None, status: str | None = None, owner_user: str | None = None, owner_agent: str | None = None, priority: int | None = None, tag: str | None = None, parent: str | None = None, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, epic: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskSearchResponse:
3844 def search( 3845 self, 3846 org: str, 3847 *, 3848 q: str | None = None, 3849 query: str | None = None, 3850 status: str | None = None, 3851 owner_user: str | None = None, 3852 owner_agent: str | None = None, 3853 priority: int | None = None, 3854 tag: str | None = None, 3855 parent: str | None = None, 3856 source_scope: str | None = None, 3857 source_type: str | None = None, 3858 source_id: str | None = None, 3859 epic: str | None = None, 3860 limit: int | None = None, 3861 after_cursor: str | None = None, 3862 ) -> OrgTaskSearchResponse: 3863 """ 3864 Search an organization's tasks 3865 Performs a full-text search over org-owned tasks for the specified 3866 organization and returns matching results. Combine `q` with the optional 3867 filters to narrow the result set further. When no query is provided, the 3868 endpoint behaves like a filtered list. 3869 The `query` field in the response echoes the effective search query. 3870 Explicitly personal, team, or agent tasks are excluded here. 3871 3872 Args: 3873 org: Organization ID (`org_...`) whose org-owned tasks should be returned. 3874 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3875 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3876 status: Filter results by status. One of `"open"`, `"in_progress"`, `"in_review"`, or `"done"`. Omit to include all statuses. 3877 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3878 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3879 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3880 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3881 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3882 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3883 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3884 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3885 epic: Return only tasks with this exact epic label. 3886 limit: Maximum number of tasks to return. Capped at 100. 3887 after_cursor: Opaque cursor returned by the previous page. 3888 3889 Returns: 3890 Successful response 3891 """ 3892 query: dict[str, object] = {} 3893 if q is not None: 3894 query["q"] = q 3895 if query is not None: 3896 query["query"] = query 3897 if status is not None: 3898 query["status"] = status 3899 if owner_user is not None: 3900 query["owner_user"] = owner_user 3901 if owner_agent is not None: 3902 query["owner_agent"] = owner_agent 3903 if priority is not None: 3904 query["priority"] = priority 3905 if tag is not None: 3906 query["tag"] = tag 3907 if parent is not None: 3908 query["parent"] = parent 3909 if source_scope is not None: 3910 query["source_scope"] = source_scope 3911 if source_type is not None: 3912 query["source_type"] = source_type 3913 if source_id is not None: 3914 query["source_id"] = source_id 3915 if epic is not None: 3916 query["epic"] = epic 3917 if limit is not None: 3918 query["limit"] = limit 3919 if after_cursor is not None: 3920 query["after_cursor"] = after_cursor 3921 return self._http.request( 3922 f"/api/v1/orgs/{org}/tasks/search", 3923 query=query, 3924 response_type=OrgTaskSearchResponse, 3925 )
Search an organization's tasks
Performs a full-text search over org-owned tasks for the specified
organization and returns matching results. Combine q with the optional
filters to narrow the result set further. When no query is provided, the
endpoint behaves like a filtered list.
The query field in the response echoes the effective search query.
Explicitly personal, team, or agent tasks are excluded here.
Arguments:
- org: Organization ID (
org_...) whose org-owned tasks should be returned. - q: Full-text search query matched against task names and descriptions. Takes precedence over
querywhen both are provided. - query: Alias for
q. Useqwhen possible; this parameter exists for compatibility. - status: Filter results by status. One of
"open","in_progress","in_review", or"done". Omit to include all statuses. - owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (
usr_...). - owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (
agi_...). - priority: Filter tasks by priority, from 0 (highest) to 4 (lowest).
- tag: Return only tasks carrying this tag (matched against the canonical lowercase form).
- parent: Return only subtasks of the given task (
tsk_...), or passnoneto return only top-level tasks. - source_scope: Return only tasks whose source matches this container. Must be supplied with
source_typeandsource_id. - source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters.
- source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters.
- epic: Return only tasks with this exact epic label.
- limit: Maximum number of tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
class
OrgThreadResource:
3928class OrgThreadResource: 3929 def __init__(self, http: SyncHttpClient): 3930 self._http = http 3931 3932 def list(self, org: str, *, key: str | None = None) -> OrgThreadListResponse: 3933 """ 3934 List organization-visibility threads 3935 Returns org-visibility threads for the specified organization. Every member 3936 of the organization can list these threads; they require no team membership. 3937 App-scoped developer tokens for the organization's app can list them too. 3938 3939 Args: 3940 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3941 key: Optional exact thread key, for example `support-room`. 3942 3943 Returns: 3944 Successful response 3945 """ 3946 query: dict[str, object] = {} 3947 if key is not None: 3948 query["key"] = key 3949 return self._http.request( 3950 f"/api/v1/orgs/{org}/threads", 3951 query=query, 3952 response_type=OrgThreadListResponse, 3953 ) 3954 3955 def create(self, org: str, input: OrgThreadCreateInput) -> Thread: 3956 """ 3957 Create an organization-visibility thread 3958 Creates a thread owned by the organization rather than a team, user, or agent. 3959 Every member of the organization can read and post without joining. The 3960 authenticated caller must be an organization administrator, or use an 3961 app-scoped developer token for the organization's app. 3962 When `thread.key` is supplied, creation is idempotent: a second call with the 3963 same key returns the existing org-visibility thread instead of inserting a 3964 duplicate. 3965 3966 Args: 3967 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3968 input: Request body. 3969 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3970 input.thread: Attributes for the new thread. Visibility is forced to `org`. 3971 3972 Returns: 3973 The organization-visibility thread. 3974 """ 3975 return self._http.request( 3976 f"/api/v1/orgs/{org}/threads", 3977 method="POST", 3978 body=input, 3979 response_type=Thread, 3980 )
OrgThreadResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
3932 def list(self, org: str, *, key: str | None = None) -> OrgThreadListResponse: 3933 """ 3934 List organization-visibility threads 3935 Returns org-visibility threads for the specified organization. Every member 3936 of the organization can list these threads; they require no team membership. 3937 App-scoped developer tokens for the organization's app can list them too. 3938 3939 Args: 3940 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3941 key: Optional exact thread key, for example `support-room`. 3942 3943 Returns: 3944 Successful response 3945 """ 3946 query: dict[str, object] = {} 3947 if key is not None: 3948 query["key"] = key 3949 return self._http.request( 3950 f"/api/v1/orgs/{org}/threads", 3951 query=query, 3952 response_type=OrgThreadListResponse, 3953 )
List organization-visibility threads Returns org-visibility threads for the specified organization. Every member of the organization can list these threads; they require no team membership. App-scoped developer tokens for the organization's app can list them too.
Arguments:
- org: Organization ID (
org_...) whose org-visibility threads should be listed. - key: Optional exact thread key, for example
support-room.
Returns:
Successful response
def
create( self, org: str, input: OrgThreadCreateInput) -> archastro.platform.types.threads.Thread:
3955 def create(self, org: str, input: OrgThreadCreateInput) -> Thread: 3956 """ 3957 Create an organization-visibility thread 3958 Creates a thread owned by the organization rather than a team, user, or agent. 3959 Every member of the organization can read and post without joining. The 3960 authenticated caller must be an organization administrator, or use an 3961 app-scoped developer token for the organization's app. 3962 When `thread.key` is supplied, creation is idempotent: a second call with the 3963 same key returns the existing org-visibility thread instead of inserting a 3964 duplicate. 3965 3966 Args: 3967 org: Organization ID (`org_...`) whose org-visibility threads should be listed. 3968 input: Request body. 3969 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3970 input.thread: Attributes for the new thread. Visibility is forced to `org`. 3971 3972 Returns: 3973 The organization-visibility thread. 3974 """ 3975 return self._http.request( 3976 f"/api/v1/orgs/{org}/threads", 3977 method="POST", 3978 body=input, 3979 response_type=Thread, 3980 )
Create an organization-visibility thread
Creates a thread owned by the organization rather than a team, user, or agent.
Every member of the organization can read and post without joining. The
authenticated caller must be an organization administrator, or use an
app-scoped developer token for the organization's app.
When thread.key is supplied, creation is idempotent: a second call with the
same key returns the existing org-visibility thread instead of inserting a
duplicate.
Arguments:
- org: Organization ID (
org_...) whose org-visibility threads should be listed. - input: Request body.
- input.skip_welcome_message: When
true, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults tofalse. - input.thread: Attributes for the new thread. Visibility is forced to
org.
Returns:
The organization-visibility thread.
class
OrgResource:
3983class OrgResource: 3984 def __init__(self, http: SyncHttpClient): 3985 self._http = http 3986 self.tasks = OrgTaskResource(http) 3987 self.threads = OrgThreadResource(http) 3988 3989 def list( 3990 self, *, search: str | None = None, page: int | None = None, page_size: int | None = None 3991 ) -> OrgListResponse: 3992 """ 3993 Search organizations 3994 Returns a paginated list of organizations within the authenticated app scope, 3995 optionally filtered by a free-text search term matched against name, slug, and 3996 domain (case-insensitive). Results are ordered by relevance when a search term 3997 is provided, and by creation time descending otherwise. 3998 The response includes only public-facing organization fields: ID, name, domain, 3999 and logo. Use the developer-scoped org endpoints to access full organization 4000 records. 4001 Pagination is offset-based. Pass `page` and `page_size` to navigate through 4002 results. The `has_next` and `has_prev` fields indicate whether adjacent pages 4003 exist. 4004 4005 Args: 4006 search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app. 4007 page: Page number to retrieve, starting at `1`. Defaults to `1` when omitted. 4008 page_size: Number of organizations to return per page. Defaults to `25`; maximum is `100`. 4009 4010 Returns: 4011 Successful response 4012 """ 4013 query: dict[str, object] = {} 4014 if search is not None: 4015 query["search"] = search 4016 if page is not None: 4017 query["page"] = page 4018 if page_size is not None: 4019 query["page_size"] = page_size 4020 return self._http.request("/api/v1/orgs", query=query, response_type=OrgListResponse) 4021 4022 def artifacts( 4023 self, 4024 org: str, 4025 *, 4026 limit: int | None = None, 4027 after_cursor: str | None = None, 4028 group_key: str | None = None, 4029 group_key_prefix: str | None = None, 4030 ) -> OrgArtifactsResponse: 4031 """ 4032 List completed organization artifacts 4033 Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded. 4034 4035 Args: 4036 org: Organization ID. 4037 limit: Maximum snapshots returned, from 1 to 100. 4038 after_cursor: Opaque cursor for the next page of older snapshots. 4039 group_key: Exact, case-sensitive grouping key. 4040 group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key. 4041 4042 Returns: 4043 Successful response 4044 """ 4045 query: dict[str, object] = {} 4046 if limit is not None: 4047 query["limit"] = limit 4048 if after_cursor is not None: 4049 query["after_cursor"] = after_cursor 4050 if group_key is not None: 4051 query["group_key"] = group_key 4052 if group_key_prefix is not None: 4053 query["group_key_prefix"] = group_key_prefix 4054 return self._http.request( 4055 f"/api/v1/orgs/{org}/artifacts", 4056 query=query, 4057 response_type=OrgArtifactsResponse, 4058 ) 4059 4060 def linked_accounts( 4061 self, 4062 org: str, 4063 *, 4064 user: builtins.list[str] | None = None, 4065 limit: int | None = None, 4066 after_cursor: str | None = None, 4067 ) -> OrgLinkedAccountsResponse: 4068 """ 4069 List an organization's linked accounts 4070 Returns the GitHub login each user in the organization signed in with, so 4071 clients can tell that a pull request's author and a Platform user are the 4072 same person. Users who never signed in with GitHub are absent. Any viewer 4073 acting within the organization can list them; other viewers get 404. 4074 Pass `user` to look up specific users instead of listing the whole 4075 organization. Results are ordered by user and paginated forward with 4076 `after_cursor`. 4077 4078 Args: 4079 org: Organization ID (`org_...`) whose linked accounts should be listed. 4080 user: Up to 100 user IDs (`usr_...`) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. 4081 limit: Maximum accounts returned, from 1 to 100. 4082 after_cursor: Opaque cursor for the next page. 4083 4084 Returns: 4085 Successful response 4086 """ 4087 query: dict[str, object] = {} 4088 if user is not None: 4089 query["user"] = user 4090 if limit is not None: 4091 query["limit"] = limit 4092 if after_cursor is not None: 4093 query["after_cursor"] = after_cursor 4094 return self._http.request( 4095 f"/api/v1/orgs/{org}/linked_accounts", 4096 query=query, 4097 response_type=OrgLinkedAccountsResponse, 4098 ) 4099 4100 def task_epics( 4101 self, 4102 org: str, 4103 *, 4104 source_scope: str | None = None, 4105 source_type: str | None = None, 4106 source_id: str | None = None, 4107 top_priority: int | None = None, 4108 include_closed: bool | None = None, 4109 limit: int | None = None, 4110 after_cursor: str | None = None, 4111 ) -> OrgTaskEpicsResponse: 4112 """ 4113 List an organization's epic summaries 4114 Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 4115 4116 Args: 4117 org: Organization ID (`org_...`) owning the tasks. 4118 source_scope: Exact source scope; supply all three source fields. 4119 source_type: Exact source type. 4120 source_id: Exact source ID. 4121 top_priority: Exact highest open priority, from 0 to 4. 4122 include_closed: Include epics with no non-closed tasks; defaults to false. 4123 limit: Maximum epics; defaults to 50, capped at 100. 4124 after_cursor: Opaque forward cursor from the preceding page. 4125 4126 Returns: 4127 Successful response 4128 """ 4129 query: dict[str, object] = {} 4130 if source_scope is not None: 4131 query["source_scope"] = source_scope 4132 if source_type is not None: 4133 query["source_type"] = source_type 4134 if source_id is not None: 4135 query["source_id"] = source_id 4136 if top_priority is not None: 4137 query["top_priority"] = top_priority 4138 if include_closed is not None: 4139 query["include_closed"] = include_closed 4140 if limit is not None: 4141 query["limit"] = limit 4142 if after_cursor is not None: 4143 query["after_cursor"] = after_cursor 4144 return self._http.request( 4145 f"/api/v1/orgs/{org}/task_epics", 4146 query=query, 4147 response_type=OrgTaskEpicsResponse, 4148 )
OrgResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, *, search: str | None = None, page: int | None = None, page_size: int | None = None) -> OrgListResponse:
3989 def list( 3990 self, *, search: str | None = None, page: int | None = None, page_size: int | None = None 3991 ) -> OrgListResponse: 3992 """ 3993 Search organizations 3994 Returns a paginated list of organizations within the authenticated app scope, 3995 optionally filtered by a free-text search term matched against name, slug, and 3996 domain (case-insensitive). Results are ordered by relevance when a search term 3997 is provided, and by creation time descending otherwise. 3998 The response includes only public-facing organization fields: ID, name, domain, 3999 and logo. Use the developer-scoped org endpoints to access full organization 4000 records. 4001 Pagination is offset-based. Pass `page` and `page_size` to navigate through 4002 results. The `has_next` and `has_prev` fields indicate whether adjacent pages 4003 exist. 4004 4005 Args: 4006 search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app. 4007 page: Page number to retrieve, starting at `1`. Defaults to `1` when omitted. 4008 page_size: Number of organizations to return per page. Defaults to `25`; maximum is `100`. 4009 4010 Returns: 4011 Successful response 4012 """ 4013 query: dict[str, object] = {} 4014 if search is not None: 4015 query["search"] = search 4016 if page is not None: 4017 query["page"] = page 4018 if page_size is not None: 4019 query["page_size"] = page_size 4020 return self._http.request("/api/v1/orgs", query=query, response_type=OrgListResponse)
Search organizations
Returns a paginated list of organizations within the authenticated app scope,
optionally filtered by a free-text search term matched against name, slug, and
domain (case-insensitive). Results are ordered by relevance when a search term
is provided, and by creation time descending otherwise.
The response includes only public-facing organization fields: ID, name, domain,
and logo. Use the developer-scoped org endpoints to access full organization
records.
Pagination is offset-based. Pass page and page_size to navigate through
results. The has_next and has_prev fields indicate whether adjacent pages
exist.
Arguments:
- search: Free-text search term matched against organization name, slug, and domain (case-insensitive). Omit to return all organizations in the app.
- page: Page number to retrieve, starting at
1. Defaults to1when omitted. - page_size: Number of organizations to return per page. Defaults to
25; maximum is100.
Returns:
Successful response
def
artifacts( self, org: str, *, limit: int | None = None, after_cursor: str | None = None, group_key: str | None = None, group_key_prefix: str | None = None) -> OrgArtifactsResponse:
4022 def artifacts( 4023 self, 4024 org: str, 4025 *, 4026 limit: int | None = None, 4027 after_cursor: str | None = None, 4028 group_key: str | None = None, 4029 group_key_prefix: str | None = None, 4030 ) -> OrgArtifactsResponse: 4031 """ 4032 List completed organization artifacts 4033 Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded. 4034 4035 Args: 4036 org: Organization ID. 4037 limit: Maximum snapshots returned, from 1 to 100. 4038 after_cursor: Opaque cursor for the next page of older snapshots. 4039 group_key: Exact, case-sensitive grouping key. 4040 group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key. 4041 4042 Returns: 4043 Successful response 4044 """ 4045 query: dict[str, object] = {} 4046 if limit is not None: 4047 query["limit"] = limit 4048 if after_cursor is not None: 4049 query["after_cursor"] = after_cursor 4050 if group_key is not None: 4051 query["group_key"] = group_key 4052 if group_key_prefix is not None: 4053 query["group_key_prefix"] = group_key_prefix 4054 return self._http.request( 4055 f"/api/v1/orgs/{org}/artifacts", 4056 query=query, 4057 response_type=OrgArtifactsResponse, 4058 )
List completed organization artifacts Returns completed system-owned organization snapshots, newest first. Private user, team, agent and thread artifacts are excluded.
Arguments:
- org: Organization ID.
- limit: Maximum snapshots returned, from 1 to 100.
- after_cursor: Opaque cursor for the next page of older snapshots.
- group_key: Exact, case-sensitive grouping key.
- group_key_prefix: Nonempty literal group prefix; mutually exclusive with group_key.
Returns:
Successful response
def
linked_accounts( self, org: str, *, user: list[str] | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgLinkedAccountsResponse:
4060 def linked_accounts( 4061 self, 4062 org: str, 4063 *, 4064 user: builtins.list[str] | None = None, 4065 limit: int | None = None, 4066 after_cursor: str | None = None, 4067 ) -> OrgLinkedAccountsResponse: 4068 """ 4069 List an organization's linked accounts 4070 Returns the GitHub login each user in the organization signed in with, so 4071 clients can tell that a pull request's author and a Platform user are the 4072 same person. Users who never signed in with GitHub are absent. Any viewer 4073 acting within the organization can list them; other viewers get 404. 4074 Pass `user` to look up specific users instead of listing the whole 4075 organization. Results are ordered by user and paginated forward with 4076 `after_cursor`. 4077 4078 Args: 4079 org: Organization ID (`org_...`) whose linked accounts should be listed. 4080 user: Up to 100 user IDs (`usr_...`) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. 4081 limit: Maximum accounts returned, from 1 to 100. 4082 after_cursor: Opaque cursor for the next page. 4083 4084 Returns: 4085 Successful response 4086 """ 4087 query: dict[str, object] = {} 4088 if user is not None: 4089 query["user"] = user 4090 if limit is not None: 4091 query["limit"] = limit 4092 if after_cursor is not None: 4093 query["after_cursor"] = after_cursor 4094 return self._http.request( 4095 f"/api/v1/orgs/{org}/linked_accounts", 4096 query=query, 4097 response_type=OrgLinkedAccountsResponse, 4098 )
List an organization's linked accounts
Returns the GitHub login each user in the organization signed in with, so
clients can tell that a pull request's author and a Platform user are the
same person. Users who never signed in with GitHub are absent. Any viewer
acting within the organization can list them; other viewers get 404.
Pass user to look up specific users instead of listing the whole
organization. Results are ordered by user and paginated forward with
after_cursor.
Arguments:
- org: Organization ID (
org_...) whose linked accounts should be listed. - user: Up to 100 user IDs (
usr_...) to look up. Omit to list every user in the organization. Users in the list who are outside the organization or have no linked account are absent. - limit: Maximum accounts returned, from 1 to 100.
- after_cursor: Opaque cursor for the next page.
Returns:
Successful response
def
task_epics( self, org: str, *, source_scope: str | None = None, source_type: str | None = None, source_id: str | None = None, top_priority: int | None = None, include_closed: bool | None = None, limit: int | None = None, after_cursor: str | None = None) -> OrgTaskEpicsResponse:
4100 def task_epics( 4101 self, 4102 org: str, 4103 *, 4104 source_scope: str | None = None, 4105 source_type: str | None = None, 4106 source_id: str | None = None, 4107 top_priority: int | None = None, 4108 include_closed: bool | None = None, 4109 limit: int | None = None, 4110 after_cursor: str | None = None, 4111 ) -> OrgTaskEpicsResponse: 4112 """ 4113 List an organization's epic summaries 4114 Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created. 4115 4116 Args: 4117 org: Organization ID (`org_...`) owning the tasks. 4118 source_scope: Exact source scope; supply all three source fields. 4119 source_type: Exact source type. 4120 source_id: Exact source ID. 4121 top_priority: Exact highest open priority, from 0 to 4. 4122 include_closed: Include epics with no non-closed tasks; defaults to false. 4123 limit: Maximum epics; defaults to 50, capped at 100. 4124 after_cursor: Opaque forward cursor from the preceding page. 4125 4126 Returns: 4127 Successful response 4128 """ 4129 query: dict[str, object] = {} 4130 if source_scope is not None: 4131 query["source_scope"] = source_scope 4132 if source_type is not None: 4133 query["source_type"] = source_type 4134 if source_id is not None: 4135 query["source_id"] = source_id 4136 if top_priority is not None: 4137 query["top_priority"] = top_priority 4138 if include_closed is not None: 4139 query["include_closed"] = include_closed 4140 if limit is not None: 4141 query["limit"] = limit 4142 if after_cursor is not None: 4143 query["after_cursor"] = after_cursor 4144 return self._http.request( 4145 f"/api/v1/orgs/{org}/task_epics", 4146 query=query, 4147 response_type=OrgTaskEpicsResponse, 4148 )
List an organization's epic summaries Groups org-owned tasks by their exact epic label, ordered by label. Closed tasks include cancelled tasks, but cancelled prerequisites still block. Source filters select the tasks summarized; blockers outside that selection still affect readiness. Root ranking is capped per epic and root_blockers_partial is true when that graph is truncated. No epic entity is created.
Arguments:
- org: Organization ID (
org_...) owning the tasks. - source_scope: Exact source scope; supply all three source fields.
- source_type: Exact source type.
- source_id: Exact source ID.
- top_priority: Exact highest open priority, from 0 to 4.
- include_closed: Include epics with no non-closed tasks; defaults to false.
- limit: Maximum epics; defaults to 50, capped at 100.
- after_cursor: Opaque forward cursor from the preceding page.
Returns:
Successful response