archastro.platform.v1.resources.users
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: 1d4ce5e7f7c6 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.system import SystemAccessToken 15from ...types.tasks import Task 16from ...types.threads import Thread 17from ...types.users import User, UserInvite 18 19 20class UserTaskCreateInputTask(TypedDict, total=False): 21 description: str | None 22 "Optional long-form description or notes for the task. Supports plain text." 23 due_date: datetime | None 24 "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." 25 epic: str | None 26 "Optional free-form grouping label." 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 source_id: str | None 42 "Source object identity (for example `ArchAstro/firstlanding`)." 43 source_scope: str | None 44 "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`." 45 source_type: str | None 46 "Kind of source object (for example `repository`)." 47 status: str | None 48 'Initial status for the task. One of `"open"`, `"in_progress"`, or `"done"`. Defaults to `"open"` when omitted.' 49 tags: list[str] | None 50 "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated." 51 thread: str | None 52 "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." 53 54 55class UserTaskCreateInput(TypedDict, total=False): 56 "Create a task for an owner" 57 58 agent: str | None 59 "Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the task owner." 60 org: str | None 61 "Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team." 62 task: Required[UserTaskCreateInputTask] 63 "Attributes for the task to create. `name` is required; all other fields are optional." 64 team: str | None 65 "Team ID (`tem_...`). The task will be owned by this team." 66 67 68class UserThreadCreateInputThreadMembersItem(TypedDict): 69 id: str 70 "Public user (`usr_...`) or agent (`agt_...`) ID matching `type`." 71 type: Literal["user", "agent"] 72 "Member kind. Use `user` for a user ID or `agent` for an agent ID." 73 74 75class UserThreadCreateInputThreadProfilePicture(TypedDict, total=False): 76 data: str | None 77 "Base64-encoded image bytes." 78 filename: str | None 79 "Original filename of the uploaded image, used for display and content-type inference." 80 mime_type: str | None 81 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.' 82 83 84class UserThreadCreateInputThreadSettings(TypedDict, total=False): 85 agent_enabled: bool | None 86 "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." 87 88 89class UserThreadCreateInputThread(TypedDict, total=False): 90 create_legacy_agent: bool | None 91 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 92 description: str | None 93 "Optional longer description of the thread's purpose. `null` if not provided." 94 is_unlisted: bool | None 95 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 96 key: str | None 97 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 98 kind: Literal["personal"] | None 99 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers." 100 members: list[UserThreadCreateInputThreadMembersItem] | None 101 "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." 102 metadata: dict[str, Any] | None 103 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 104 muted: bool | None 105 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 106 org_id: str | None 107 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 108 profile_picture: UserThreadCreateInputThreadProfilePicture | None 109 "Optional profile image for the thread, provided as a base64-encoded payload." 110 settings: UserThreadCreateInputThreadSettings | None 111 "Configuration overrides for the thread, such as AI model selection and context window settings." 112 slug: str | None 113 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 114 title: str | None 115 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 116 visibility: Literal["team", "restricted", "private"] | None 117 "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." 118 119 120class UserThreadCreateInput(TypedDict, total=False): 121 "Create a thread for a user" 122 123 skip_welcome_message: bool | None 124 "When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`." 125 thread: Required[UserThreadCreateInputThread] 126 "Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields." 127 128 129class TokenCreateInput(TypedDict, total=False): 130 "Create a personal access token" 131 132 expires_in_days: int | None 133 "Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`." 134 name: str | None 135 'Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only.' 136 scopes: list[str] | None 137 "Optional OAuth scopes to stamp on the token. Omit for `full_access`." 138 139 140class UserInvitesInputInvite(TypedDict, total=False): 141 metadata: dict[str, Any] | None 142 "Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object." 143 persona_id: str | None 144 "ID of the persona to associate with this invite (`per_...`). `null` if the invite is not bound to a persona." 145 thread_id: str | None 146 "ID of the thread to associate with this invite (`thr_...`). `null` if the invite is not bound to a thread." 147 148 149class UserInvitesInput(TypedDict): 150 "Create a user invite" 151 152 invite: UserInvitesInputInvite 153 "Parameters for the new invite. See the UserInviteCreateParams schema for field details." 154 155 156class UserProfileInputProfilePicture(TypedDict, total=False): 157 data: str | None 158 "Base64-encoded binary content of the image file." 159 filename: str | None 160 "Original filename of the image, used for storage metadata." 161 mime_type: str | None 162 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.' 163 164 165class UserProfileInput(TypedDict, total=False): 166 "Update the current user's profile" 167 168 alias: str | None 169 "Short display alias shown in place of the full name in compact UI contexts." 170 full_name: str | None 171 "Updated display name for the user." 172 metadata: dict[str, Any] | None 173 "Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it." 174 profile_picture: UserProfileInputProfilePicture | None 175 "New profile picture to upload as a base64-encoded image. Replaces any existing picture." 176 177 178class UserTaskListResponseDataItemCreatedByActorProfilePicture(BaseModel): 179 file: str | None = Field( 180 default=None, 181 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 182 ) 183 height: int | None = Field( 184 default=None, description="Height of the image in pixels. `null` if not known." 185 ) 186 media: str | None = Field( 187 default=None, 188 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 189 ) 190 mime_type: str | None = Field( 191 default=None, 192 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 193 ) 194 refresh_url: str | None = Field( 195 default=None, 196 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.", 197 ) 198 url: str | None = Field( 199 default=None, 200 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.", 201 ) 202 width: int | None = Field( 203 default=None, description="Width of the image in pixels. `null` if not known." 204 ) 205 206 207class UserTaskListResponseDataItemCreatedByActor(BaseModel): 208 alias: str | None = Field( 209 default=None, 210 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 211 ) 212 id: str | None = Field( 213 default=None, 214 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 215 ) 216 name: str | None = Field( 217 default=None, 218 description="Display name of the actor shown in the UI. `null` if no name is set.", 219 ) 220 profile_picture: UserTaskListResponseDataItemCreatedByActorProfilePicture | None = Field( 221 default=None, 222 description="Profile picture for the actor. `null` if the actor has no profile picture.", 223 ) 224 225 226class UserTaskListResponseDataItemCurrentLease(BaseModel): 227 expires_at: datetime = Field( 228 ..., description="Server-calculated lease expiry in ISO 8601 format." 229 ) 230 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 231 session_name: str = Field( 232 ..., description="Display name supplied by the coding session that holds the lease." 233 ) 234 235 236class UserTaskListResponseDataItemOwnerActorProfilePicture(BaseModel): 237 file: str | None = Field( 238 default=None, 239 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 240 ) 241 height: int | None = Field( 242 default=None, description="Height of the image in pixels. `null` if not known." 243 ) 244 media: str | None = Field( 245 default=None, 246 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 247 ) 248 mime_type: str | None = Field( 249 default=None, 250 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 251 ) 252 refresh_url: str | None = Field( 253 default=None, 254 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.", 255 ) 256 url: str | None = Field( 257 default=None, 258 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.", 259 ) 260 width: int | None = Field( 261 default=None, description="Width of the image in pixels. `null` if not known." 262 ) 263 264 265class UserTaskListResponseDataItemOwnerActor(BaseModel): 266 alias: str | None = Field( 267 default=None, 268 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 269 ) 270 id: str | None = Field( 271 default=None, 272 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 273 ) 274 name: str | None = Field( 275 default=None, 276 description="Display name of the actor shown in the UI. `null` if no name is set.", 277 ) 278 profile_picture: UserTaskListResponseDataItemOwnerActorProfilePicture | None = Field( 279 default=None, 280 description="Profile picture for the actor. `null` if the actor has no profile picture.", 281 ) 282 283 284class UserTaskListResponseDataItem(BaseModel): 285 agent: str | None = Field( 286 default=None, 287 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 288 ) 289 blocked_by_count: int | None = Field( 290 default=None, 291 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 292 ) 293 closed_at: datetime | None = Field( 294 default=None, 295 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 296 ) 297 comments_count: int | None = Field( 298 default=None, description="Total number of comments posted on this task." 299 ) 300 created_at: datetime | None = Field( 301 default=None, description="When the task was created (ISO 8601)." 302 ) 303 created_by_actor: UserTaskListResponseDataItemCreatedByActor | None = Field( 304 default=None, 305 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).", 306 ) 307 created_by_agent: str | None = Field( 308 default=None, 309 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.", 310 ) 311 created_by_user: str | None = Field( 312 default=None, 313 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.", 314 ) 315 current_lease: UserTaskListResponseDataItemCurrentLease | None = Field( 316 default=None, 317 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.", 318 ) 319 description: str | None = Field( 320 default=None, 321 description="Long-form description or notes for the task. `null` if no description has been provided.", 322 ) 323 due_date: datetime | None = Field( 324 default=None, 325 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 326 ) 327 epic: str | None = Field( 328 default=None, 329 description="Free-form grouping label. `null` when the task is not in an epic.", 330 ) 331 id: str = Field(..., description="Task ID (`tsk_...`).") 332 is_blocked: bool | None = Field( 333 default=None, 334 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 335 ) 336 links: dict[str, Any] | None = Field( 337 default=None, 338 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 339 ) 340 metadata: dict[str, Any] | None = Field( 341 default=None, 342 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 343 ) 344 name: str = Field(..., description="Human-readable title of the task.") 345 org: str | None = Field( 346 default=None, 347 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 348 ) 349 owner_actor: UserTaskListResponseDataItemOwnerActor | None = Field( 350 default=None, 351 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).", 352 ) 353 owner_agent: str | None = Field( 354 default=None, 355 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.", 356 ) 357 owner_user: str | None = Field( 358 default=None, 359 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.", 360 ) 361 parent: str | None = Field( 362 default=None, 363 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 364 ) 365 priority: int | None = Field( 366 default=None, 367 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 368 ) 369 sandbox: str | None = Field( 370 default=None, 371 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 372 ) 373 source_id: str | None = Field( 374 default=None, 375 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 376 ) 377 source_scope: str | None = Field( 378 default=None, 379 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`.", 380 ) 381 source_type: str | None = Field( 382 default=None, 383 description="Kind of source object (for example `repository`). `null` when the task has no source.", 384 ) 385 status: str = Field( 386 ..., 387 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 388 ) 389 subtasks_count: int | None = Field( 390 default=None, 391 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 392 ) 393 tags: list[str] | None = Field( 394 default=None, 395 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 396 ) 397 team: str | None = Field( 398 default=None, 399 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 400 ) 401 thread: str | None = Field( 402 default=None, 403 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.", 404 ) 405 updated_at: datetime | None = Field( 406 default=None, description="When the task was last modified (ISO 8601)." 407 ) 408 user: str | None = Field( 409 default=None, 410 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 411 ) 412 413 414class UserTaskListResponse(BaseModel): 415 """ 416 Successful response 417 """ 418 419 after_cursor: str | None = None 420 before_cursor: str | None = None 421 data: list[UserTaskListResponseDataItem] = Field( 422 ..., description="Array of task objects matching the requested filters." 423 ) 424 has_more: bool 425 426 427class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(BaseModel): 428 file: str | None = Field( 429 default=None, 430 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 431 ) 432 height: int | None = Field( 433 default=None, description="Height of the image in pixels. `null` if not known." 434 ) 435 media: str | None = Field( 436 default=None, 437 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 438 ) 439 mime_type: str | None = Field( 440 default=None, 441 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 442 ) 443 refresh_url: str | None = Field( 444 default=None, 445 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.", 446 ) 447 url: str | None = Field( 448 default=None, 449 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.", 450 ) 451 width: int | None = Field( 452 default=None, description="Width of the image in pixels. `null` if not known." 453 ) 454 455 456class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(BaseModel): 457 alias: str | None = Field( 458 default=None, 459 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 460 ) 461 id: str | None = Field( 462 default=None, 463 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 464 ) 465 name: str | None = Field( 466 default=None, 467 description="Display name of the actor shown in the UI. `null` if no name is set.", 468 ) 469 profile_picture: ( 470 UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None 471 ) = Field( 472 default=None, 473 description="Profile picture for the actor. `null` if the actor has no profile picture.", 474 ) 475 476 477class UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(BaseModel): 478 expires_at: datetime = Field( 479 ..., description="Server-calculated lease expiry in ISO 8601 format." 480 ) 481 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 482 session_name: str = Field( 483 ..., description="Display name supplied by the coding session that holds the lease." 484 ) 485 486 487class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(BaseModel): 488 file: str | None = Field( 489 default=None, 490 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 491 ) 492 height: int | None = Field( 493 default=None, description="Height of the image in pixels. `null` if not known." 494 ) 495 media: str | None = Field( 496 default=None, 497 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 498 ) 499 mime_type: str | None = Field( 500 default=None, 501 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 502 ) 503 refresh_url: str | None = Field( 504 default=None, 505 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.", 506 ) 507 url: str | None = Field( 508 default=None, 509 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.", 510 ) 511 width: int | None = Field( 512 default=None, description="Width of the image in pixels. `null` if not known." 513 ) 514 515 516class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(BaseModel): 517 alias: str | None = Field( 518 default=None, 519 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 520 ) 521 id: str | None = Field( 522 default=None, 523 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 524 ) 525 name: str | None = Field( 526 default=None, 527 description="Display name of the actor shown in the UI. `null` if no name is set.", 528 ) 529 profile_picture: ( 530 UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None 531 ) = Field( 532 default=None, 533 description="Profile picture for the actor. `null` if the actor has no profile picture.", 534 ) 535 536 537class UserTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): 538 agent: str | None = Field( 539 default=None, 540 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 541 ) 542 blocked_by_count: int | None = Field( 543 default=None, 544 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 545 ) 546 closed_at: datetime | None = Field( 547 default=None, 548 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 549 ) 550 comments_count: int | None = Field( 551 default=None, description="Total number of comments posted on this task." 552 ) 553 created_at: datetime | None = Field( 554 default=None, description="When the task was created (ISO 8601)." 555 ) 556 created_by_actor: UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor | None = Field( 557 default=None, 558 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).", 559 ) 560 created_by_agent: str | None = Field( 561 default=None, 562 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.", 563 ) 564 created_by_user: str | None = Field( 565 default=None, 566 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.", 567 ) 568 current_lease: UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease | None = Field( 569 default=None, 570 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.", 571 ) 572 description: str | None = Field( 573 default=None, 574 description="Long-form description or notes for the task. `null` if no description has been provided.", 575 ) 576 due_date: datetime | None = Field( 577 default=None, 578 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 579 ) 580 epic: str | None = Field( 581 default=None, 582 description="Free-form grouping label. `null` when the task is not in an epic.", 583 ) 584 id: str = Field(..., description="Task ID (`tsk_...`).") 585 is_blocked: bool | None = Field( 586 default=None, 587 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 588 ) 589 links: dict[str, Any] | None = Field( 590 default=None, 591 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 592 ) 593 metadata: dict[str, Any] | None = Field( 594 default=None, 595 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 596 ) 597 name: str = Field(..., description="Human-readable title of the task.") 598 org: str | None = Field( 599 default=None, 600 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 601 ) 602 owner_actor: UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor | None = Field( 603 default=None, 604 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).", 605 ) 606 owner_agent: str | None = Field( 607 default=None, 608 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.", 609 ) 610 owner_user: str | None = Field( 611 default=None, 612 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.", 613 ) 614 parent: str | None = Field( 615 default=None, 616 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 617 ) 618 priority: int | None = Field( 619 default=None, 620 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 621 ) 622 sandbox: str | None = Field( 623 default=None, 624 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 625 ) 626 source_id: str | None = Field( 627 default=None, 628 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 629 ) 630 source_scope: str | None = Field( 631 default=None, 632 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`.", 633 ) 634 source_type: str | None = Field( 635 default=None, 636 description="Kind of source object (for example `repository`). `null` when the task has no source.", 637 ) 638 status: str = Field( 639 ..., 640 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 641 ) 642 subtasks_count: int | None = Field( 643 default=None, 644 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 645 ) 646 tags: list[str] | None = Field( 647 default=None, 648 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 649 ) 650 team: str | None = Field( 651 default=None, 652 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 653 ) 654 thread: str | None = Field( 655 default=None, 656 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.", 657 ) 658 updated_at: datetime | None = Field( 659 default=None, description="When the task was last modified (ISO 8601)." 660 ) 661 user: str | None = Field( 662 default=None, 663 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 664 ) 665 666 667class UserTaskBlockerCyclesResponseDataItem(BaseModel): 668 tasks: list[UserTaskBlockerCyclesResponseDataItemTasksItem] = Field( 669 ..., description="Every unfinished task in this cyclic blocker component." 670 ) 671 672 673class UserTaskBlockerCyclesResponse(BaseModel): 674 """ 675 Successful response 676 """ 677 678 after_cursor: str | None = None 679 before_cursor: str | None = None 680 data: list[UserTaskBlockerCyclesResponseDataItem] 681 has_more: bool 682 683 684class UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): 685 file: str | None = Field( 686 default=None, 687 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 688 ) 689 height: int | None = Field( 690 default=None, description="Height of the image in pixels. `null` if not known." 691 ) 692 media: str | None = Field( 693 default=None, 694 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 695 ) 696 mime_type: str | None = Field( 697 default=None, 698 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 699 ) 700 refresh_url: str | None = Field( 701 default=None, 702 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.", 703 ) 704 url: str | None = Field( 705 default=None, 706 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.", 707 ) 708 width: int | None = Field( 709 default=None, description="Width of the image in pixels. `null` if not known." 710 ) 711 712 713class UserTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): 714 alias: str | None = Field( 715 default=None, 716 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 717 ) 718 id: str | None = Field( 719 default=None, 720 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 721 ) 722 name: str | None = Field( 723 default=None, 724 description="Display name of the actor shown in the UI. `null` if no name is set.", 725 ) 726 profile_picture: UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( 727 default=None, 728 description="Profile picture for the actor. `null` if the actor has no profile picture.", 729 ) 730 731 732class UserTaskReadyResponseDataItemTaskCurrentLease(BaseModel): 733 expires_at: datetime = Field( 734 ..., description="Server-calculated lease expiry in ISO 8601 format." 735 ) 736 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 737 session_name: str = Field( 738 ..., description="Display name supplied by the coding session that holds the lease." 739 ) 740 741 742class UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): 743 file: str | None = Field( 744 default=None, 745 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 746 ) 747 height: int | None = Field( 748 default=None, description="Height of the image in pixels. `null` if not known." 749 ) 750 media: str | None = Field( 751 default=None, 752 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 753 ) 754 mime_type: str | None = Field( 755 default=None, 756 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 757 ) 758 refresh_url: str | None = Field( 759 default=None, 760 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.", 761 ) 762 url: str | None = Field( 763 default=None, 764 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.", 765 ) 766 width: int | None = Field( 767 default=None, description="Width of the image in pixels. `null` if not known." 768 ) 769 770 771class UserTaskReadyResponseDataItemTaskOwnerActor(BaseModel): 772 alias: str | None = Field( 773 default=None, 774 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 775 ) 776 id: str | None = Field( 777 default=None, 778 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 779 ) 780 name: str | None = Field( 781 default=None, 782 description="Display name of the actor shown in the UI. `null` if no name is set.", 783 ) 784 profile_picture: UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( 785 default=None, 786 description="Profile picture for the actor. `null` if the actor has no profile picture.", 787 ) 788 789 790class UserTaskReadyResponseDataItemTask(BaseModel): 791 agent: str | None = Field( 792 default=None, 793 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 794 ) 795 blocked_by_count: int | None = Field( 796 default=None, 797 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 798 ) 799 closed_at: datetime | None = Field( 800 default=None, 801 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 802 ) 803 comments_count: int | None = Field( 804 default=None, description="Total number of comments posted on this task." 805 ) 806 created_at: datetime | None = Field( 807 default=None, description="When the task was created (ISO 8601)." 808 ) 809 created_by_actor: UserTaskReadyResponseDataItemTaskCreatedByActor | None = Field( 810 default=None, 811 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).", 812 ) 813 created_by_agent: str | None = Field( 814 default=None, 815 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.", 816 ) 817 created_by_user: str | None = Field( 818 default=None, 819 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.", 820 ) 821 current_lease: UserTaskReadyResponseDataItemTaskCurrentLease | None = Field( 822 default=None, 823 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.", 824 ) 825 description: str | None = Field( 826 default=None, 827 description="Long-form description or notes for the task. `null` if no description has been provided.", 828 ) 829 due_date: datetime | None = Field( 830 default=None, 831 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 832 ) 833 epic: str | None = Field( 834 default=None, 835 description="Free-form grouping label. `null` when the task is not in an epic.", 836 ) 837 id: str = Field(..., description="Task ID (`tsk_...`).") 838 is_blocked: bool | None = Field( 839 default=None, 840 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 841 ) 842 links: dict[str, Any] | None = Field( 843 default=None, 844 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 845 ) 846 metadata: dict[str, Any] | None = Field( 847 default=None, 848 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 849 ) 850 name: str = Field(..., description="Human-readable title of the task.") 851 org: str | None = Field( 852 default=None, 853 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 854 ) 855 owner_actor: UserTaskReadyResponseDataItemTaskOwnerActor | None = Field( 856 default=None, 857 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).", 858 ) 859 owner_agent: str | None = Field( 860 default=None, 861 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.", 862 ) 863 owner_user: str | None = Field( 864 default=None, 865 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.", 866 ) 867 parent: str | None = Field( 868 default=None, 869 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 870 ) 871 priority: int | None = Field( 872 default=None, 873 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 874 ) 875 sandbox: str | None = Field( 876 default=None, 877 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 878 ) 879 source_id: str | None = Field( 880 default=None, 881 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 882 ) 883 source_scope: str | None = Field( 884 default=None, 885 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`.", 886 ) 887 source_type: str | None = Field( 888 default=None, 889 description="Kind of source object (for example `repository`). `null` when the task has no source.", 890 ) 891 status: str = Field( 892 ..., 893 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 894 ) 895 subtasks_count: int | None = Field( 896 default=None, 897 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 898 ) 899 tags: list[str] | None = Field( 900 default=None, 901 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 902 ) 903 team: str | None = Field( 904 default=None, 905 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 906 ) 907 thread: str | None = Field( 908 default=None, 909 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.", 910 ) 911 updated_at: datetime | None = Field( 912 default=None, description="When the task was last modified (ISO 8601)." 913 ) 914 user: str | None = Field( 915 default=None, 916 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 917 ) 918 919 920class UserTaskReadyResponseDataItem(BaseModel): 921 readiness: Literal["ready", "blocked", "leased"] = Field( 922 ..., description="One of `ready`, `blocked`, or `leased`." 923 ) 924 reason: Literal["open_blockers", "active_lease"] | None = Field( 925 default=None, 926 description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", 927 ) 928 task: UserTaskReadyResponseDataItemTask = Field( 929 ..., description="The task evaluated for readiness." 930 ) 931 932 933class UserTaskReadyResponse(BaseModel): 934 """ 935 Successful response 936 """ 937 938 after_cursor: str | None = None 939 authoritative: bool = Field( 940 ..., 941 description="Always false because projections can lag writes and a later claim can race this read.", 942 ) 943 before_cursor: str | None = None 944 data: list[UserTaskReadyResponseDataItem] 945 has_more: bool 946 947 948class UserTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): 949 file: str | None = Field( 950 default=None, 951 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 952 ) 953 height: int | None = Field( 954 default=None, description="Height of the image in pixels. `null` if not known." 955 ) 956 media: str | None = Field( 957 default=None, 958 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 959 ) 960 mime_type: str | None = Field( 961 default=None, 962 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 963 ) 964 refresh_url: str | None = Field( 965 default=None, 966 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.", 967 ) 968 url: str | None = Field( 969 default=None, 970 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.", 971 ) 972 width: int | None = Field( 973 default=None, description="Width of the image in pixels. `null` if not known." 974 ) 975 976 977class UserTaskSearchResponseDataItemCreatedByActor(BaseModel): 978 alias: str | None = Field( 979 default=None, 980 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 981 ) 982 id: str | None = Field( 983 default=None, 984 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 985 ) 986 name: str | None = Field( 987 default=None, 988 description="Display name of the actor shown in the UI. `null` if no name is set.", 989 ) 990 profile_picture: UserTaskSearchResponseDataItemCreatedByActorProfilePicture | None = Field( 991 default=None, 992 description="Profile picture for the actor. `null` if the actor has no profile picture.", 993 ) 994 995 996class UserTaskSearchResponseDataItemCurrentLease(BaseModel): 997 expires_at: datetime = Field( 998 ..., description="Server-calculated lease expiry in ISO 8601 format." 999 ) 1000 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 1001 session_name: str = Field( 1002 ..., description="Display name supplied by the coding session that holds the lease." 1003 ) 1004 1005 1006class UserTaskSearchResponseDataItemOwnerActorProfilePicture(BaseModel): 1007 file: str | None = Field( 1008 default=None, 1009 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1010 ) 1011 height: int | None = Field( 1012 default=None, description="Height of the image in pixels. `null` if not known." 1013 ) 1014 media: str | None = Field( 1015 default=None, 1016 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1017 ) 1018 mime_type: str | None = Field( 1019 default=None, 1020 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1021 ) 1022 refresh_url: str | None = Field( 1023 default=None, 1024 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.", 1025 ) 1026 url: str | None = Field( 1027 default=None, 1028 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.", 1029 ) 1030 width: int | None = Field( 1031 default=None, description="Width of the image in pixels. `null` if not known." 1032 ) 1033 1034 1035class UserTaskSearchResponseDataItemOwnerActor(BaseModel): 1036 alias: str | None = Field( 1037 default=None, 1038 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1039 ) 1040 id: str | None = Field( 1041 default=None, 1042 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1043 ) 1044 name: str | None = Field( 1045 default=None, 1046 description="Display name of the actor shown in the UI. `null` if no name is set.", 1047 ) 1048 profile_picture: UserTaskSearchResponseDataItemOwnerActorProfilePicture | None = Field( 1049 default=None, 1050 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1051 ) 1052 1053 1054class UserTaskSearchResponseDataItem(BaseModel): 1055 agent: str | None = Field( 1056 default=None, 1057 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 1058 ) 1059 blocked_by_count: int | None = Field( 1060 default=None, 1061 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 1062 ) 1063 closed_at: datetime | None = Field( 1064 default=None, 1065 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 1066 ) 1067 comments_count: int | None = Field( 1068 default=None, description="Total number of comments posted on this task." 1069 ) 1070 created_at: datetime | None = Field( 1071 default=None, description="When the task was created (ISO 8601)." 1072 ) 1073 created_by_actor: UserTaskSearchResponseDataItemCreatedByActor | None = Field( 1074 default=None, 1075 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).", 1076 ) 1077 created_by_agent: str | None = Field( 1078 default=None, 1079 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.", 1080 ) 1081 created_by_user: str | None = Field( 1082 default=None, 1083 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.", 1084 ) 1085 current_lease: UserTaskSearchResponseDataItemCurrentLease | None = Field( 1086 default=None, 1087 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.", 1088 ) 1089 description: str | None = Field( 1090 default=None, 1091 description="Long-form description or notes for the task. `null` if no description has been provided.", 1092 ) 1093 due_date: datetime | None = Field( 1094 default=None, 1095 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 1096 ) 1097 epic: str | None = Field( 1098 default=None, 1099 description="Free-form grouping label. `null` when the task is not in an epic.", 1100 ) 1101 id: str = Field(..., description="Task ID (`tsk_...`).") 1102 is_blocked: bool | None = Field( 1103 default=None, 1104 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 1105 ) 1106 links: dict[str, Any] | None = Field( 1107 default=None, 1108 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 1109 ) 1110 metadata: dict[str, Any] | None = Field( 1111 default=None, 1112 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 1113 ) 1114 name: str = Field(..., description="Human-readable title of the task.") 1115 org: str | None = Field( 1116 default=None, 1117 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 1118 ) 1119 owner_actor: UserTaskSearchResponseDataItemOwnerActor | None = Field( 1120 default=None, 1121 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).", 1122 ) 1123 owner_agent: str | None = Field( 1124 default=None, 1125 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.", 1126 ) 1127 owner_user: str | None = Field( 1128 default=None, 1129 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.", 1130 ) 1131 parent: str | None = Field( 1132 default=None, 1133 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 1134 ) 1135 priority: int | None = Field( 1136 default=None, 1137 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1138 ) 1139 sandbox: str | None = Field( 1140 default=None, 1141 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1142 ) 1143 source_id: str | None = Field( 1144 default=None, 1145 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1146 ) 1147 source_scope: str | None = Field( 1148 default=None, 1149 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`.", 1150 ) 1151 source_type: str | None = Field( 1152 default=None, 1153 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1154 ) 1155 status: str = Field( 1156 ..., 1157 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 1158 ) 1159 subtasks_count: int | None = Field( 1160 default=None, 1161 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1162 ) 1163 tags: list[str] | None = Field( 1164 default=None, 1165 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1166 ) 1167 team: str | None = Field( 1168 default=None, 1169 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1170 ) 1171 thread: str | None = Field( 1172 default=None, 1173 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.", 1174 ) 1175 updated_at: datetime | None = Field( 1176 default=None, description="When the task was last modified (ISO 8601)." 1177 ) 1178 user: str | None = Field( 1179 default=None, 1180 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1181 ) 1182 1183 1184class UserTaskSearchResponse(BaseModel): 1185 """ 1186 Successful response 1187 """ 1188 1189 after_cursor: str | None = None 1190 before_cursor: str | None = None 1191 data: list[UserTaskSearchResponseDataItem] = Field( 1192 ..., description="Array of task objects matching the query and filters." 1193 ) 1194 has_more: bool 1195 query: str 1196 1197 1198class UserThreadListResponseDataItemParentMessageAclAddItem(BaseModel): 1199 actions: list[str] = Field( 1200 ..., 1201 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1202 ) 1203 principal: str | None = Field( 1204 default=None, 1205 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"`.', 1206 ) 1207 principal_type: str = Field( 1208 ..., 1209 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1210 ) 1211 1212 1213class UserThreadListResponseDataItemParentMessageAclGrantsItem(BaseModel): 1214 actions: list[str] = Field( 1215 ..., 1216 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1217 ) 1218 principal: str | None = Field( 1219 default=None, 1220 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"`.', 1221 ) 1222 principal_type: str = Field( 1223 ..., 1224 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1225 ) 1226 1227 1228class UserThreadListResponseDataItemParentMessageAclRemoveItem(BaseModel): 1229 principal: str | None = Field( 1230 default=None, 1231 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"`.', 1232 ) 1233 principal_type: str = Field( 1234 ..., 1235 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1236 ) 1237 1238 1239class UserThreadListResponseDataItemParentMessageAcl(BaseModel): 1240 add: list[UserThreadListResponseDataItemParentMessageAclAddItem] | None = Field( 1241 default=None, 1242 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1243 ) 1244 grants: list[UserThreadListResponseDataItemParentMessageAclGrantsItem] | None = Field( 1245 default=None, 1246 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`.", 1247 ) 1248 remove: list[UserThreadListResponseDataItemParentMessageAclRemoveItem] | None = Field( 1249 default=None, 1250 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1251 ) 1252 1253 1254class UserThreadListResponseDataItemParentMessageActorsItemProfilePicture(BaseModel): 1255 file: str | None = Field( 1256 default=None, 1257 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1258 ) 1259 height: int | None = Field( 1260 default=None, description="Height of the image in pixels. `null` if not known." 1261 ) 1262 media: str | None = Field( 1263 default=None, 1264 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1265 ) 1266 mime_type: str | None = Field( 1267 default=None, 1268 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1269 ) 1270 refresh_url: str | None = Field( 1271 default=None, 1272 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.", 1273 ) 1274 url: str | None = Field( 1275 default=None, 1276 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.", 1277 ) 1278 width: int | None = Field( 1279 default=None, description="Width of the image in pixels. `null` if not known." 1280 ) 1281 1282 1283class UserThreadListResponseDataItemParentMessageActorsItem(BaseModel): 1284 alias: str | None = Field( 1285 default=None, 1286 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1287 ) 1288 id: str | None = Field( 1289 default=None, 1290 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1291 ) 1292 name: str | None = Field( 1293 default=None, 1294 description="Display name of the actor shown in the UI. `null` if no name is set.", 1295 ) 1296 profile_picture: UserThreadListResponseDataItemParentMessageActorsItemProfilePicture | None = ( 1297 Field( 1298 default=None, 1299 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1300 ) 1301 ) 1302 1303 1304class UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource(BaseModel): 1305 file: str | None = Field( 1306 default=None, 1307 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1308 ) 1309 height: int | None = Field( 1310 default=None, description="Height of the image in pixels. `null` if not known." 1311 ) 1312 media: str | None = Field( 1313 default=None, 1314 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1315 ) 1316 mime_type: str | None = Field( 1317 default=None, 1318 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1319 ) 1320 refresh_url: str | None = Field( 1321 default=None, 1322 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.", 1323 ) 1324 url: str | None = Field( 1325 default=None, 1326 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.", 1327 ) 1328 width: int | None = Field( 1329 default=None, description="Width of the image in pixels. `null` if not known." 1330 ) 1331 1332 1333class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(BaseModel): 1334 file: str | None = Field( 1335 default=None, 1336 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1337 ) 1338 height: int | None = Field( 1339 default=None, description="Height of the image in pixels. `null` if not known." 1340 ) 1341 media: str | None = Field( 1342 default=None, 1343 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1344 ) 1345 mime_type: str | None = Field( 1346 default=None, 1347 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1348 ) 1349 refresh_url: str | None = Field( 1350 default=None, 1351 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.", 1352 ) 1353 url: str | None = Field( 1354 default=None, 1355 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.", 1356 ) 1357 width: int | None = Field( 1358 default=None, description="Width of the image in pixels. `null` if not known." 1359 ) 1360 1361 1362class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(BaseModel): 1363 content_type: str | None = Field( 1364 default=None, 1365 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 1366 ) 1367 created_at: datetime | None = Field( 1368 default=None, description="When this variant was created (ISO 8601)." 1369 ) 1370 file: str | None = Field( 1371 default=None, 1372 description="ID of the underlying storage file that backs this variant (`fil_...`).", 1373 ) 1374 filename: str | None = Field( 1375 default=None, 1376 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 1377 ) 1378 height: int | None = Field( 1379 default=None, description="Height of this variant in pixels. `null` if not recorded." 1380 ) 1381 id: str = Field(..., description="Media variant ID (`mvr_...`).") 1382 image_source: ( 1383 UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | None 1384 ) = Field( 1385 default=None, 1386 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 1387 ) 1388 updated_at: datetime | None = Field( 1389 default=None, description="When this variant was last updated (ISO 8601)." 1390 ) 1391 url: str | None = Field( 1392 default=None, 1393 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 1394 ) 1395 variant_key: str | None = Field( 1396 default=None, 1397 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 1398 ) 1399 width: int | None = Field( 1400 default=None, description="Width of this variant in pixels. `null` if not recorded." 1401 ) 1402 1403 1404class UserThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): 1405 content_type: str | None = Field( 1406 default=None, 1407 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1408 ) 1409 description: str | None = Field( 1410 default=None, 1411 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.", 1412 ) 1413 filename: str | None = Field( 1414 default=None, 1415 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1416 ) 1417 height: int | None = Field( 1418 default=None, 1419 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 1420 ) 1421 id: str = Field(..., description="Unique identifier for this attachment within the message.") 1422 image_height: int | None = Field( 1423 default=None, 1424 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1425 ) 1426 image_source: UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource | None = ( 1427 Field( 1428 default=None, 1429 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 1430 ) 1431 ) 1432 image_url: str | None = Field( 1433 default=None, 1434 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 1435 ) 1436 image_width: int | None = Field( 1437 default=None, 1438 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1439 ) 1440 media_type: str | None = Field( 1441 default=None, 1442 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 1443 ) 1444 name: str | None = Field( 1445 default=None, 1446 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 1447 ) 1448 object: dict[str, Any] | None = Field( 1449 default=None, 1450 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`. Omitted on other types.", 1451 ) 1452 title: str | None = Field( 1453 default=None, 1454 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.", 1455 ) 1456 type: str = Field( 1457 ..., 1458 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, or `"chart"`. Determines which additional fields are present.', 1459 ) 1460 url: str | None = Field( 1461 default=None, 1462 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.", 1463 ) 1464 variants: ( 1465 list[UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None 1466 ) = Field( 1467 default=None, 1468 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 1469 ) 1470 version: int | None = Field( 1471 default=None, 1472 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 1473 ) 1474 width: int | None = Field( 1475 default=None, 1476 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 1477 ) 1478 1479 1480class UserThreadListResponseDataItemParentMessageReactionsItem(BaseModel): 1481 payload: dict[str, Any] | None = Field( 1482 default=None, 1483 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 1484 ) 1485 type: str = Field( 1486 ..., 1487 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 1488 ) 1489 user: str | None = Field( 1490 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 1491 ) 1492 1493 1494class UserThreadListResponseDataItemParentMessage(BaseModel): 1495 acl: UserThreadListResponseDataItemParentMessageAcl | None = Field( 1496 default=None, 1497 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.", 1498 ) 1499 actors: list[UserThreadListResponseDataItemParentMessageActorsItem] | None = Field( 1500 default=None, 1501 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 1502 ) 1503 agent: str | None = Field( 1504 default=None, 1505 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 1506 ) 1507 agent_mode: Literal["cli", "embedded"] | None = Field( 1508 default=None, 1509 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.", 1510 ) 1511 attachments: list[UserThreadListResponseDataItemParentMessageAttachmentsItem] | None = Field( 1512 default=None, 1513 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 1514 ) 1515 branched_thread: str | None = Field( 1516 default=None, 1517 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 1518 ) 1519 content: str | None = Field( 1520 default=None, 1521 description="Text content of the message. `null` for messages that contain only attachments.", 1522 ) 1523 created_at: str | None = Field( 1524 default=None, description="When the message was posted (ISO 8601)." 1525 ) 1526 has_replies: bool | None = Field( 1527 default=None, 1528 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 1529 ) 1530 id: str = Field(..., description="Message ID (`msg_...`).") 1531 idempotency_key: str | None = Field( 1532 default=None, 1533 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 1534 ) 1535 is_deleted: bool | None = Field( 1536 default=None, 1537 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.", 1538 ) 1539 legacy_agent: str | None = Field( 1540 default=None, 1541 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 1542 ) 1543 metadata: dict[str, Any] | None = Field( 1544 default=None, 1545 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 1546 ) 1547 org: str | None = Field( 1548 default=None, description="ID of the organization that owns this message (`org_...`)." 1549 ) 1550 reactions: list[UserThreadListResponseDataItemParentMessageReactionsItem] | None = Field( 1551 default=None, 1552 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.", 1553 ) 1554 rendering_mode: str | None = Field( 1555 default=None, 1556 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.', 1557 ) 1558 replies: list[dict[str, Any]] | None = Field( 1559 default=None, 1560 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 1561 ) 1562 replies_after_cursor: str | None = Field( 1563 default=None, 1564 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 1565 ) 1566 replies_before_cursor: str | None = Field( 1567 default=None, 1568 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 1569 ) 1570 reply_count: int | None = Field( 1571 default=None, 1572 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 1573 ) 1574 reply_to: dict[str, Any] | None = Field( 1575 default=None, 1576 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.", 1577 ) 1578 root_message_id: str | None = Field( 1579 default=None, 1580 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.", 1581 ) 1582 sandbox: str | None = Field( 1583 default=None, 1584 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 1585 ) 1586 team: str | None = Field( 1587 default=None, 1588 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 1589 ) 1590 thread: str | None = Field( 1591 default=None, description="ID of the thread this message belongs to (`thr_...`)." 1592 ) 1593 type: str | None = Field( 1594 default=None, 1595 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.", 1596 ) 1597 user: str | dict[str, Any] | None = Field( 1598 default=None, 1599 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.", 1600 ) 1601 visibility: Literal["default", "private"] | None = Field( 1602 default=None, 1603 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.", 1604 ) 1605 1606 1607class UserThreadListResponseDataItemParticipantsItem(BaseModel): 1608 alias: str | None = Field( 1609 default=None, description="Short handle or alias for the user. `null` if not set." 1610 ) 1611 app: str | None = Field( 1612 default=None, 1613 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.", 1614 ) 1615 app_name: str | None = Field( 1616 default=None, 1617 description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", 1618 ) 1619 created_by_agent_user: str | None = Field( 1620 default=None, 1621 description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", 1622 ) 1623 created_by_developer: str | None = Field( 1624 default=None, 1625 description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", 1626 ) 1627 created_by_org: str | None = Field( 1628 default=None, 1629 description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", 1630 ) 1631 created_by_team: str | None = Field( 1632 default=None, 1633 description="Team that created this user (`tem_...`). `null` unless created as a team.", 1634 ) 1635 created_by_user: str | None = Field( 1636 default=None, 1637 description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", 1638 ) 1639 email: str | None = Field(default=None, description="Email address of the user.") 1640 id: str = Field(..., description="User ID (`usr_...`).") 1641 is_system_user: bool | None = Field( 1642 default=None, 1643 description="`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", 1644 ) 1645 metadata: dict[str, Any] | None = Field( 1646 default=None, 1647 description="Arbitrary key-value metadata attached to the user. Defaults to an empty object.", 1648 ) 1649 name: str | None = Field( 1650 default=None, 1651 description="Full display name of the user. `null` if the user has not set a name.", 1652 ) 1653 org: str | None = Field( 1654 default=None, 1655 description="ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", 1656 ) 1657 org_name: str | None = Field( 1658 default=None, 1659 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.", 1660 ) 1661 org_role: str | None = Field( 1662 default=None, 1663 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.', 1664 ) 1665 org_slug: str | None = Field( 1666 default=None, 1667 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.", 1668 ) 1669 sandbox: str | None = Field( 1670 default=None, 1671 description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", 1672 ) 1673 sandbox_name: str | None = Field( 1674 default=None, 1675 description="Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", 1676 ) 1677 1678 1679class UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem(BaseModel): 1680 actions: list[str] = Field( 1681 ..., 1682 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1683 ) 1684 principal: str | None = Field( 1685 default=None, 1686 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"`.', 1687 ) 1688 principal_type: str = Field( 1689 ..., 1690 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1691 ) 1692 1693 1694class UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(BaseModel): 1695 actions: list[str] = Field( 1696 ..., 1697 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1698 ) 1699 principal: str | None = Field( 1700 default=None, 1701 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"`.', 1702 ) 1703 principal_type: str = Field( 1704 ..., 1705 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1706 ) 1707 1708 1709class UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(BaseModel): 1710 principal: str | None = Field( 1711 default=None, 1712 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"`.', 1713 ) 1714 principal_type: str = Field( 1715 ..., 1716 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1717 ) 1718 1719 1720class UserThreadListResponseDataItemParticipatingAgentsItemAcl(BaseModel): 1721 add: list[UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem] | None = Field( 1722 default=None, 1723 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1724 ) 1725 grants: list[UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem] | None = Field( 1726 default=None, 1727 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`.", 1728 ) 1729 remove: list[UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem] | None = Field( 1730 default=None, 1731 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1732 ) 1733 1734 1735class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo( 1736 BaseModel 1737): 1738 file: str | None = Field( 1739 default=None, 1740 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1741 ) 1742 height: int | None = Field( 1743 default=None, description="Height of the image in pixels. `null` if not known." 1744 ) 1745 media: str | None = Field( 1746 default=None, 1747 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1748 ) 1749 mime_type: str | None = Field( 1750 default=None, 1751 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1752 ) 1753 refresh_url: str | None = Field( 1754 default=None, 1755 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.", 1756 ) 1757 url: str | None = Field( 1758 default=None, 1759 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.", 1760 ) 1761 width: int | None = Field( 1762 default=None, description="Width of the image in pixels. `null` if not known." 1763 ) 1764 1765 1766class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 1767 BaseModel 1768): 1769 description: str | None = Field( 1770 default=None, 1771 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 1772 ) 1773 name: str = Field( 1774 ..., 1775 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 1776 ) 1777 required: bool = Field( 1778 ..., 1779 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 1780 ) 1781 type: str = Field( 1782 ..., 1783 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 1784 ) 1785 1786 1787class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills( 1788 BaseModel 1789): 1790 participants: dict[str, Any] | None = Field( 1791 default=None, 1792 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 1793 ) 1794 payload: dict[str, Any] | None = Field( 1795 default=None, 1796 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.", 1797 ) 1798 1799 1800class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract( 1801 BaseModel 1802): 1803 input_schema: dict[str, Any] | None = Field( 1804 default=None, 1805 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 1806 ) 1807 participants: ( 1808 list[ 1809 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem 1810 ] 1811 | None 1812 ) = Field( 1813 default=None, 1814 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.", 1815 ) 1816 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 1817 ..., 1818 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 1819 ) 1820 1821 1822class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails( 1823 BaseModel 1824): 1825 automation_type: str | None = Field( 1826 default=None, 1827 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 1828 ) 1829 invoke_contract: ( 1830 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract 1831 | None 1832 ) = Field( 1833 default=None, 1834 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.", 1835 ) 1836 type: Literal["automation"] = Field( 1837 default="automation", 1838 description="Template-details discriminator. Always `automation` for this variant.", 1839 ) 1840 1841 1842class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem( 1843 BaseModel 1844): 1845 description: str | None = Field( 1846 default=None, 1847 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.", 1848 ) 1849 details: ( 1850 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails 1851 | None 1852 ) = Field( 1853 default=None, 1854 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 1855 ) 1856 display_name: str | None = Field( 1857 default=None, 1858 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`.", 1859 ) 1860 id: str | None = Field( 1861 default=None, 1862 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 1863 ) 1864 kind: str = Field( 1865 ..., 1866 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 1867 ) 1868 lookup_key: str | None = Field( 1869 default=None, 1870 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 1871 ) 1872 name: str | None = Field( 1873 default=None, 1874 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`.", 1875 ) 1876 readme_url: str | None = Field( 1877 default=None, 1878 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`.", 1879 ) 1880 virtual_path: str | None = Field( 1881 default=None, 1882 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 1883 ) 1884 1885 1886class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(BaseModel): 1887 category_keys: list[str] | None = Field( 1888 default=None, 1889 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 1890 ) 1891 created_at: str | None = Field( 1892 default=None, description="When the Solution config was first imported (ISO 8601)." 1893 ) 1894 description: str | None = Field( 1895 default=None, 1896 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.", 1897 ) 1898 events: dict[str, Any] | None = Field( 1899 default=None, 1900 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.", 1901 ) 1902 id: str = Field(..., description="Solution config ID (`cfg_...`).") 1903 image_url: str | None = Field( 1904 default=None, 1905 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, and always `null` for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.", 1906 ) 1907 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 1908 latest_solution: str | None = Field( 1909 default=None, 1910 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 1911 ) 1912 latest_version: str | None = Field( 1913 default=None, 1914 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 1915 ) 1916 lookup_key: str | None = Field( 1917 default=None, 1918 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 1919 ) 1920 metadata: dict[str, Any] | None = Field( 1921 default=None, 1922 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.", 1923 ) 1924 name: str | None = Field( 1925 default=None, 1926 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 1927 ) 1928 org: str | None = Field( 1929 default=None, 1930 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.", 1931 ) 1932 org_logo: ( 1933 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo 1934 | None 1935 ) = Field( 1936 default=None, 1937 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.", 1938 ) 1939 org_name: str | None = Field( 1940 default=None, 1941 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 1942 ) 1943 org_slug: str | None = Field( 1944 default=None, 1945 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.", 1946 ) 1947 owners: list[str] = Field( 1948 ..., 1949 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 1950 ) 1951 readme_url: str | None = Field( 1952 default=None, 1953 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`.", 1954 ) 1955 screenshot_urls: list[str] | None = Field( 1956 default=None, 1957 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.", 1958 ) 1959 solution_id: str | None = Field( 1960 default=None, 1961 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.", 1962 ) 1963 solution_version: str | None = Field( 1964 default=None, 1965 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 1966 ) 1967 tag_keys: list[str] | None = Field( 1968 default=None, 1969 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 1970 ) 1971 template_kind: str | None = Field( 1972 default=None, 1973 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 1974 ) 1975 templates: list[ 1976 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem 1977 ] = Field( 1978 ..., 1979 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.", 1980 ) 1981 updated_at: str | None = Field( 1982 default=None, description="When the Solution config was last modified (ISO 8601)." 1983 ) 1984 upgrade_available: bool = Field( 1985 ..., 1986 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.", 1987 ) 1988 virtual_path: str | None = Field( 1989 default=None, 1990 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.", 1991 ) 1992 1993 1994class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(BaseModel): 1995 file: str | None = Field( 1996 default=None, 1997 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1998 ) 1999 height: int | None = Field( 2000 default=None, description="Height of the image in pixels. `null` if not known." 2001 ) 2002 media: str | None = Field( 2003 default=None, 2004 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2005 ) 2006 mime_type: str | None = Field( 2007 default=None, 2008 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2009 ) 2010 refresh_url: str | None = Field( 2011 default=None, 2012 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.", 2013 ) 2014 url: str | None = Field( 2015 default=None, 2016 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.", 2017 ) 2018 width: int | None = Field( 2019 default=None, description="Width of the image in pixels. `null` if not known." 2020 ) 2021 2022 2023class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 2024 BaseModel 2025): 2026 description: str | None = Field( 2027 default=None, 2028 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 2029 ) 2030 name: str = Field( 2031 ..., 2032 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 2033 ) 2034 required: bool = Field( 2035 ..., 2036 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2037 ) 2038 type: str = Field( 2039 ..., 2040 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2041 ) 2042 2043 2044class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills( 2045 BaseModel 2046): 2047 participants: dict[str, Any] | None = Field( 2048 default=None, 2049 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2050 ) 2051 payload: dict[str, Any] | None = Field( 2052 default=None, 2053 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.", 2054 ) 2055 2056 2057class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract( 2058 BaseModel 2059): 2060 input_schema: dict[str, Any] | None = Field( 2061 default=None, 2062 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2063 ) 2064 participants: ( 2065 list[ 2066 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2067 ] 2068 | None 2069 ) = Field( 2070 default=None, 2071 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.", 2072 ) 2073 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2074 ..., 2075 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2076 ) 2077 2078 2079class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails( 2080 BaseModel 2081): 2082 automation_type: str | None = Field( 2083 default=None, 2084 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2085 ) 2086 invoke_contract: ( 2087 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract 2088 | None 2089 ) = Field( 2090 default=None, 2091 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.", 2092 ) 2093 type: Literal["automation"] = Field( 2094 default="automation", 2095 description="Template-details discriminator. Always `automation` for this variant.", 2096 ) 2097 2098 2099class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem( 2100 BaseModel 2101): 2102 description: str | None = Field( 2103 default=None, 2104 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.", 2105 ) 2106 details: ( 2107 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails 2108 | None 2109 ) = Field( 2110 default=None, 2111 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2112 ) 2113 display_name: str | None = Field( 2114 default=None, 2115 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`.", 2116 ) 2117 id: str | None = Field( 2118 default=None, 2119 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2120 ) 2121 kind: str = Field( 2122 ..., 2123 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2124 ) 2125 lookup_key: str | None = Field( 2126 default=None, 2127 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2128 ) 2129 name: str | None = Field( 2130 default=None, 2131 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`.", 2132 ) 2133 readme_url: str | None = Field( 2134 default=None, 2135 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`.", 2136 ) 2137 virtual_path: str | None = Field( 2138 default=None, 2139 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2140 ) 2141 2142 2143class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(BaseModel): 2144 category_keys: list[str] | None = Field( 2145 default=None, 2146 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2147 ) 2148 created_at: str | None = Field( 2149 default=None, description="When the Solution config was first imported (ISO 8601)." 2150 ) 2151 description: str | None = Field( 2152 default=None, 2153 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.", 2154 ) 2155 events: dict[str, Any] | None = Field( 2156 default=None, 2157 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.", 2158 ) 2159 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2160 image_url: str | None = Field( 2161 default=None, 2162 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, and always `null` for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.", 2163 ) 2164 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2165 latest_solution: str | None = Field( 2166 default=None, 2167 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2168 ) 2169 latest_version: str | None = Field( 2170 default=None, 2171 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2172 ) 2173 lookup_key: str | None = Field( 2174 default=None, 2175 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2176 ) 2177 metadata: dict[str, Any] | None = Field( 2178 default=None, 2179 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.", 2180 ) 2181 name: str | None = Field( 2182 default=None, 2183 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2184 ) 2185 org: str | None = Field( 2186 default=None, 2187 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.", 2188 ) 2189 org_logo: ( 2190 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | None 2191 ) = Field( 2192 default=None, 2193 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.", 2194 ) 2195 org_name: str | None = Field( 2196 default=None, 2197 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2198 ) 2199 org_slug: str | None = Field( 2200 default=None, 2201 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.", 2202 ) 2203 owners: list[str] = Field( 2204 ..., 2205 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2206 ) 2207 readme_url: str | None = Field( 2208 default=None, 2209 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`.", 2210 ) 2211 screenshot_urls: list[str] | None = Field( 2212 default=None, 2213 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.", 2214 ) 2215 solution_id: str | None = Field( 2216 default=None, 2217 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.", 2218 ) 2219 solution_version: str | None = Field( 2220 default=None, 2221 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2222 ) 2223 tag_keys: list[str] | None = Field( 2224 default=None, 2225 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2226 ) 2227 template_kind: str | None = Field( 2228 default=None, 2229 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2230 ) 2231 templates: list[ 2232 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem 2233 ] = Field( 2234 ..., 2235 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.", 2236 ) 2237 updated_at: str | None = Field( 2238 default=None, description="When the Solution config was last modified (ISO 8601)." 2239 ) 2240 upgrade_available: bool = Field( 2241 ..., 2242 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.", 2243 ) 2244 virtual_path: str | None = Field( 2245 default=None, 2246 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.", 2247 ) 2248 2249 2250class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(BaseModel): 2251 created_at: datetime | None = Field( 2252 default=None, description="When this template config was created (ISO 8601)." 2253 ) 2254 description: str | None = Field( 2255 default=None, 2256 description="Description of the template from the config body. `null` if the current version has no `description` field.", 2257 ) 2258 display_name: str | None = Field( 2259 default=None, 2260 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 2261 ) 2262 id: str = Field(..., description="Template config ID (`cfg_...`).") 2263 kind: str = Field( 2264 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 2265 ) 2266 lookup_key: str | None = Field( 2267 default=None, 2268 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 2269 ) 2270 name: str | None = Field( 2271 default=None, 2272 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 2273 ) 2274 updated_at: datetime | None = Field( 2275 default=None, description="When this template config was last modified (ISO 8601)." 2276 ) 2277 virtual_path: str | None = Field( 2278 default=None, 2279 description="Virtual filesystem path for this template config. `null` if not set.", 2280 ) 2281 2282 2283class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution(BaseModel): 2284 current_solution: ( 2285 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | None 2286 ) = Field( 2287 default=None, 2288 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.", 2289 ) 2290 solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution = Field( 2291 ..., 2292 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.", 2293 ) 2294 template: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate = Field( 2295 ..., 2296 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2297 ) 2298 2299 2300class UserThreadListResponseDataItemParticipatingAgentsItem(BaseModel): 2301 acl: UserThreadListResponseDataItemParticipatingAgentsItemAcl | None = Field( 2302 default=None, 2303 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.", 2304 ) 2305 app: str | None = Field( 2306 default=None, description="ID of the application that owns this agent (`dap_...`)." 2307 ) 2308 created_at: str | None = Field( 2309 default=None, description="When the agent was created (ISO 8601)." 2310 ) 2311 default_model: str | None = Field( 2312 default=None, 2313 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2314 ) 2315 description: str | None = Field( 2316 default=None, 2317 description="Human-readable description of what the agent does. `null` if not set.", 2318 ) 2319 email: str | None = Field( 2320 default=None, 2321 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2322 ) 2323 id: str = Field(..., description="Agent ID (`agi_...`).") 2324 identity: str | None = Field( 2325 default=None, 2326 description="System-level identity prompt that shapes the agent's persona and behavior.", 2327 ) 2328 last_applied_template_config: str | None = Field( 2329 default=None, 2330 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2331 ) 2332 lookup_key: str | None = Field( 2333 default=None, 2334 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2335 ) 2336 metadata: dict[str, Any] | None = Field( 2337 default=None, 2338 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2339 ) 2340 name: str | None = Field( 2341 default=None, description="Human-readable display name for the agent. `null` if not set." 2342 ) 2343 org: str | None = Field( 2344 default=None, 2345 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2346 ) 2347 org_name: str | None = Field( 2348 default=None, 2349 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.", 2350 ) 2351 originator: str | None = Field( 2352 default=None, 2353 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2354 ) 2355 phone_number: str | None = Field( 2356 default=None, 2357 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2358 ) 2359 sandbox: str | None = Field( 2360 default=None, 2361 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2362 ) 2363 source_solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution | None = ( 2364 Field( 2365 default=None, 2366 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.", 2367 ) 2368 ) 2369 team: str | None = Field( 2370 default=None, 2371 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2372 ) 2373 template_upgrade_available: bool | None = Field( 2374 default=None, 2375 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`).", 2376 ) 2377 updated_at: str | None = Field( 2378 default=None, description="When the agent was last modified (ISO 8601)." 2379 ) 2380 user: str | None = Field( 2381 default=None, 2382 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 2383 ) 2384 2385 2386class UserThreadListResponseDataItemSettings(BaseModel): 2387 agent_enabled: bool | None = Field( 2388 default=None, 2389 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.", 2390 ) 2391 2392 2393class UserThreadListResponseDataItem(BaseModel): 2394 agent_user: str | None = Field( 2395 default=None, 2396 description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", 2397 ) 2398 created_at: str | None = Field( 2399 default=None, description="When the thread was created (ISO 8601)." 2400 ) 2401 creator: str | dict[str, Any] | None = Field( 2402 default=None, 2403 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.", 2404 ) 2405 description: str | None = Field( 2406 default=None, 2407 description="Optional description or purpose statement for the thread. `null` if not set.", 2408 ) 2409 id: str = Field(..., description="Thread ID (`thr_...`).") 2410 is_channel: bool | None = Field( 2411 default=None, 2412 description="Whether this thread operates as a channel a multi-member broadcast-style conversation.", 2413 ) 2414 is_default: bool | None = Field( 2415 default=None, 2416 description="Whether this is the default thread for its owner. Each user or team has at most one default thread.", 2417 ) 2418 is_transient: bool | None = Field( 2419 default=None, 2420 description="Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.", 2421 ) 2422 is_unlisted: bool | None = Field( 2423 default=None, 2424 description="Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.", 2425 ) 2426 key: str | None = Field( 2427 default=None, 2428 description="Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", 2429 ) 2430 kind: str | None = Field( 2431 default=None, 2432 description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.', 2433 ) 2434 last_activity: str | None = Field( 2435 default=None, 2436 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.", 2437 ) 2438 last_message_preview: str | None = Field( 2439 default=None, 2440 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.", 2441 ) 2442 last_message_sender: str | None = Field( 2443 default=None, 2444 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.", 2445 ) 2446 metadata: dict[str, Any] | None = Field( 2447 default=None, 2448 description="Arbitrary key-value metadata attached to the thread. Shape is application-defined; `null` if no metadata has been set.", 2449 ) 2450 muted: bool | None = Field( 2451 default=None, 2452 description="Whether the authenticated user has muted notifications for this thread. `true` suppresses all notification delivery.", 2453 ) 2454 org: str | None = Field( 2455 default=None, 2456 description="ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", 2457 ) 2458 parent_message: UserThreadListResponseDataItemParentMessage | None = Field( 2459 default=None, 2460 description="The message that spawned this thread as a sub-thread. `null` for top-level threads.", 2461 ) 2462 participant: list[str] | None = Field( 2463 default=None, 2464 description="Array of participant user IDs (`usr_...`) who are members of this thread.", 2465 ) 2466 participants: list[UserThreadListResponseDataItemParticipantsItem] | None = Field( 2467 default=None, 2468 description="Expanded participant user objects for each member of this thread. Populated only when the association is loaded.", 2469 ) 2470 participating_actor: list[str] | None = Field( 2471 default=None, 2472 description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", 2473 ) 2474 participating_agents: list[UserThreadListResponseDataItemParticipatingAgentsItem] | None = ( 2475 Field( 2476 default=None, 2477 description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", 2478 ) 2479 ) 2480 role: str | None = Field( 2481 default=None, 2482 description='The authenticated user\'s membership role in this thread, e.g. `"owner"`, `"member"`, or `"viewer"`. `null` if the user is not a member.', 2483 ) 2484 sandbox: str | None = Field( 2485 default=None, 2486 description="ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", 2487 ) 2488 settings: UserThreadListResponseDataItemSettings | None = Field( 2489 default=None, 2490 description="Per-thread configuration settings controlling AI agent behavior for this thread.", 2491 ) 2492 slug: str | None = Field( 2493 default=None, 2494 description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", 2495 ) 2496 sub_threads: list[dict[str, Any]] | None = Field( 2497 default=None, 2498 description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", 2499 ) 2500 tags: list[str] | None = Field( 2501 default=None, 2502 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.', 2503 ) 2504 team: str | None = Field( 2505 default=None, 2506 description="ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", 2507 ) 2508 title: str | None = Field( 2509 default=None, 2510 description="Human-readable name of the thread. `null` if no title has been set.", 2511 ) 2512 ttl: str | None = Field( 2513 default=None, 2514 description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", 2515 ) 2516 unread_count: int | None = Field( 2517 default=None, 2518 description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", 2519 ) 2520 updated_at: str | None = Field( 2521 default=None, description="When the thread was last modified (ISO 8601)." 2522 ) 2523 user: str | None = Field( 2524 default=None, 2525 description="ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", 2526 ) 2527 visibility: Literal["team", "restricted", "private"] = Field( 2528 ..., 2529 description="Who can read the thread: `team` for every owning-team member, `restricted` for team-readable threads with an explicit roster, or `private` for roster-only access.", 2530 ) 2531 2532 2533class UserThreadListResponse(BaseModel): 2534 """ 2535 Successful response 2536 """ 2537 2538 data: list[UserThreadListResponseDataItem] = Field( 2539 ..., 2540 description="Array of thread objects matching the requested filters and agent narrowings.", 2541 ) 2542 2543 2544class TokenListResponseDataItem(BaseModel): 2545 created_at: datetime | None = Field( 2546 default=None, description="When this token was created (ISO 8601)." 2547 ) 2548 created_by_agent_user: str | None = Field( 2549 default=None, 2550 description="Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", 2551 ) 2552 created_by_developer: str | None = Field( 2553 default=None, 2554 description="Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", 2555 ) 2556 created_by_org: str | None = Field( 2557 default=None, 2558 description="Org of the principal that minted this token (`org_...`). `null` on legacy rows.", 2559 ) 2560 created_by_team: str | None = Field( 2561 default=None, 2562 description="Team that minted this token (`tem_...`). `null` unless minted as a team.", 2563 ) 2564 created_by_user: str | None = Field( 2565 default=None, 2566 description="User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", 2567 ) 2568 expires_at: datetime | None = Field( 2569 default=None, 2570 description="When the token expires. `null` on legacy rows that predate stored expiry.", 2571 ) 2572 id: str = Field(..., description="Token ID (`sat_...`).") 2573 last_used_at: datetime | None = Field( 2574 default=None, 2575 description="When this token was last used to authenticate a request. `null` if the token has never been used.", 2576 ) 2577 name: str | None = Field( 2578 default=None, 2579 description="Human-readable label assigned to this token at creation time. `null` when no label was supplied.", 2580 ) 2581 revoked_at: datetime | None = Field( 2582 default=None, 2583 description="When this token was revoked. `null` if the token is still active.", 2584 ) 2585 scopes: str | None = Field( 2586 default=None, 2587 description="Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", 2588 ) 2589 token: str | None = Field( 2590 default=None, 2591 description="Raw bearer token string. Present only in the response to the create request; never returned again after that.", 2592 ) 2593 2594 2595class TokenListResponse(BaseModel): 2596 """ 2597 Successful response 2598 """ 2599 2600 data: list[TokenListResponseDataItem] = Field( 2601 ..., description="Array of access token objects. Raw JWT values are not included." 2602 ) 2603 2604 2605class UserArtifactsResponseDataItemImageSource(BaseModel): 2606 file: str | None = Field( 2607 default=None, 2608 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2609 ) 2610 height: int | None = Field( 2611 default=None, description="Height of the image in pixels. `null` if not known." 2612 ) 2613 media: str | None = Field( 2614 default=None, 2615 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2616 ) 2617 mime_type: str | None = Field( 2618 default=None, 2619 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2620 ) 2621 refresh_url: str | None = Field( 2622 default=None, 2623 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.", 2624 ) 2625 url: str | None = Field( 2626 default=None, 2627 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.", 2628 ) 2629 width: int | None = Field( 2630 default=None, description="Width of the image in pixels. `null` if not known." 2631 ) 2632 2633 2634class UserArtifactsResponseDataItem(BaseModel): 2635 agent: str | None = Field( 2636 default=None, 2637 description="ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.", 2638 ) 2639 content_type: str | None = Field( 2640 default=None, 2641 description='MIME type of the current version\'s file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.', 2642 ) 2643 created_at: datetime | None = Field( 2644 default=None, description="When the artifact was first created (ISO 8601)." 2645 ) 2646 current_version: str | None = Field( 2647 default=None, 2648 description="ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.", 2649 ) 2650 description: str | None = Field( 2651 default=None, 2652 description="Optional longer description of the artifact's contents or purpose. `null` if not set.", 2653 ) 2654 file: str | None = Field( 2655 default=None, 2656 description="Storage file ID for the current version (`fil_...`). `null` if no file is attached.", 2657 ) 2658 file_name: str | None = Field( 2659 default=None, 2660 description='Original filename of the current version\'s file, e.g. `"output.csv"`. `null` if no file is attached.', 2661 ) 2662 file_url: str | None = Field( 2663 default=None, 2664 description="Short-lived signed URL for downloading the current version's file. `null` if no file is attached.", 2665 ) 2666 id: str = Field(..., description="Artifact ID (`art_...`).") 2667 image_source: UserArtifactsResponseDataItemImageSource | None = Field( 2668 default=None, 2669 description='Image source metadata for rendering the current version\'s file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.', 2670 ) 2671 name: str | None = Field( 2672 default=None, 2673 description='Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.', 2674 ) 2675 org: str | None = Field( 2676 default=None, description="ID of the organization this artifact belongs to (`org_...`)." 2677 ) 2678 sandbox: str | None = Field( 2679 default=None, 2680 description="Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.", 2681 ) 2682 team: str | None = Field( 2683 default=None, 2684 description="ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.", 2685 ) 2686 thread: str | None = Field( 2687 default=None, 2688 description="ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.", 2689 ) 2690 updated_at: datetime | None = Field( 2691 default=None, description="When the artifact record was last modified (ISO 8601)." 2692 ) 2693 user: str | None = Field( 2694 default=None, 2695 description="ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.", 2696 ) 2697 version: int | None = Field( 2698 default=None, 2699 description="Current version number of the artifact. Increments each time a new version is published.", 2700 ) 2701 2702 2703class UserArtifactsResponse(BaseModel): 2704 """ 2705 Successful response 2706 """ 2707 2708 data: list[UserArtifactsResponseDataItem] = Field( 2709 ..., description="Array of artifact objects belonging to the user." 2710 ) 2711 2712 2713class UserOrgsResponseDataItem(BaseModel): 2714 created_at: datetime | None = Field( 2715 default=None, description="When this organization was created (ISO 8601)." 2716 ) 2717 description: str | None = Field( 2718 default=None, 2719 description="Short human-readable description of the organization. `null` if not set.", 2720 ) 2721 domain: str | None = Field( 2722 default=None, 2723 description='Primary domain associated with the organization, e.g. `"acme.com"`. `null` if not configured.', 2724 ) 2725 id: str = Field(..., description="Organization ID (`org_...`).") 2726 industry: str | None = Field( 2727 default=None, 2728 description='Industry category the organization belongs to, e.g. `"fintech"` or `"healthcare"`. `null` if not set.', 2729 ) 2730 name: str | None = Field( 2731 default=None, 2732 description="Display name of the organization. `null` if the org has not set a name.", 2733 ) 2734 onboarding_solution_lookup_key: str | None = Field( 2735 default=None, 2736 description="Lookup key (`sol-...`) of the Solution currently driving this org's customer onboarding the active onboarding solution pointer. Stamped when the org is linked into a vendor's network via an explore-install and re-stamped by every later solution-driven link, so the latest install wins. `null` for vendor-track orgs and invite-driven customers. The onboarding UI reads the referenced Solution's `metadata.onboarding` block to tailor the customer checklist.", 2737 ) 2738 onboarding_track: str | None = Field( 2739 default=None, 2740 description='The new-user experience track this org first completed. `"vendor"` for orgs that onboarded as service providers; `"customer"` for orgs that onboarded as buyers. `null` if onboarding was not tracked.', 2741 ) 2742 owned_products: list[str] | None = Field( 2743 default=None, 2744 description='Catalog product IDs this organization\'s plan includes, e.g. `["agent-rooms"]`, `["agent-solutions"]`, `["agent-customer-management"]`. Empty when the org has no plan. Clients use this to show which products the org actually has rather than inferring from feature flags. Derived from the org\'s plan, so it reflects what is currently paid for.', 2745 ) 2746 sandbox: str | None = Field( 2747 default=None, 2748 description="ID of the sandbox environment scoped to this organization (`snd_...`). `null` for organizations in production mode.", 2749 ) 2750 slug: str | None = Field( 2751 default=None, 2752 description="URL-safe identifier for the organization, used in vanity URLs and slug-based lookups.", 2753 ) 2754 status: str | None = Field( 2755 default=None, 2756 description='Current lifecycle status of the organization, e.g. `"active"` or `"suspended"`. `null` if the status has not been set.', 2757 ) 2758 updated_at: datetime | None = Field( 2759 default=None, description="When this organization was last modified (ISO 8601)." 2760 ) 2761 website: str | None = Field( 2762 default=None, description="Public website URL for the organization. `null` if not set." 2763 ) 2764 2765 2766class UserOrgsResponse(BaseModel): 2767 """ 2768 Successful response 2769 """ 2770 2771 data: list[UserOrgsResponseDataItem] = Field( 2772 ..., 2773 description="Array of organization objects the user belongs to. Contains at most one item.", 2774 ) 2775 2776 2777class AsyncUserTaskResource: 2778 def __init__(self, http: HttpClient): 2779 self._http = http 2780 2781 async def list( 2782 self, 2783 user: str, 2784 *, 2785 team: str | None = None, 2786 org: str | None = None, 2787 status: str | None = None, 2788 owner_user: str | None = None, 2789 owner_agent: str | None = None, 2790 priority: int | None = None, 2791 tag: str | None = None, 2792 parent: str | None = None, 2793 source_scope: str | None = None, 2794 source_type: str | None = None, 2795 source_id: str | None = None, 2796 epic: str | None = None, 2797 search: str | None = None, 2798 sort: str | None = None, 2799 order: str | None = None, 2800 due_before: str | None = None, 2801 due_after: str | None = None, 2802 overdue: bool | None = None, 2803 ready: bool | None = None, 2804 limit: int | None = None, 2805 after_cursor: str | None = None, 2806 ) -> UserTaskListResponse: 2807 """ 2808 List an owner's tasks 2809 Returns tasks owned by the specified user or team. You can narrow results using the 2810 optional filters below. By default results are returned in reverse chronological 2811 order (most recently created first); use `sort` and `order` to sort by due date or 2812 priority instead. 2813 User-authenticated callers may list their personal tasks or tasks for teams they 2814 have joined. Privileged callers provide the owner in the route; the owner's 2815 organization is implied by that principal. An explicit `org` is optional and, 2816 when set, must match the owner's organization. 2817 2818 Args: 2819 user: User ID (`usr_...`) for user-scoped tasks. 2820 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 2821 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 2822 status: Filter tasks by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to return tasks in all statuses. 2823 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 2824 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 2825 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 2826 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 2827 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 2828 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 2829 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 2830 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 2831 epic: Return only tasks with this exact epic label. 2832 search: Restrict results to tasks whose name or description contains this string. 2833 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. 2834 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 2835 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. 2836 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 2837 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. 2838 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. 2839 limit: Maximum number of tasks to return. Capped at 100. 2840 after_cursor: Opaque cursor returned by the previous page. 2841 2842 Returns: 2843 Successful response 2844 """ 2845 query: dict[str, object] = {} 2846 if team is not None: 2847 query["team"] = team 2848 if org is not None: 2849 query["org"] = org 2850 if status is not None: 2851 query["status"] = status 2852 if owner_user is not None: 2853 query["owner_user"] = owner_user 2854 if owner_agent is not None: 2855 query["owner_agent"] = owner_agent 2856 if priority is not None: 2857 query["priority"] = priority 2858 if tag is not None: 2859 query["tag"] = tag 2860 if parent is not None: 2861 query["parent"] = parent 2862 if source_scope is not None: 2863 query["source_scope"] = source_scope 2864 if source_type is not None: 2865 query["source_type"] = source_type 2866 if source_id is not None: 2867 query["source_id"] = source_id 2868 if epic is not None: 2869 query["epic"] = epic 2870 if search is not None: 2871 query["search"] = search 2872 if sort is not None: 2873 query["sort"] = sort 2874 if order is not None: 2875 query["order"] = order 2876 if due_before is not None: 2877 query["due_before"] = due_before 2878 if due_after is not None: 2879 query["due_after"] = due_after 2880 if overdue is not None: 2881 query["overdue"] = overdue 2882 if ready is not None: 2883 query["ready"] = ready 2884 if limit is not None: 2885 query["limit"] = limit 2886 if after_cursor is not None: 2887 query["after_cursor"] = after_cursor 2888 return await self._http.request( 2889 f"/api/v1/users/{user}/tasks", 2890 query=query, 2891 response_type=UserTaskListResponse, 2892 ) 2893 2894 async def create(self, user: str, input: UserTaskCreateInput) -> Task: 2895 """ 2896 Create a task for an owner 2897 Creates a new task owned by the specified user or team and returns the full 2898 task object. User-authenticated calls are attributed to the authenticated 2899 user or agent. App-scoped developer and server-to-server callers must provide 2900 the task's explicit `org` scope and an explicit `user` or `agent` actor for 2901 team tasks; a user-owned task reuses the user in the route unless an explicit 2902 agent is supplied. Every referenced principal is validated against the app, 2903 owner, and team membership before creation. 2904 2905 Args: 2906 user: User ID (`usr_...`) for user-scoped tasks. 2907 input: Request body. 2908 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 task owner. 2909 input.org: Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. 2910 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 2911 input.team: Team ID (`tem_...`). The task will be owned by this team. 2912 2913 Returns: 2914 The newly created task. 2915 """ 2916 return await self._http.request( 2917 f"/api/v1/users/{user}/tasks", 2918 method="POST", 2919 body=input, 2920 response_type=Task, 2921 ) 2922 2923 async def blocker_cycles( 2924 self, 2925 user: str, 2926 *, 2927 team: str | None = None, 2928 org: str | None = None, 2929 limit: int | None = None, 2930 after_cursor: str | None = None, 2931 ) -> UserTaskBlockerCyclesResponse: 2932 """ 2933 List task blocker cycles 2934 Runs an on-demand diagnostic over unfinished tasks owned by the specified 2935 team or user and returns a forward cursor-paginated page of complete cyclic 2936 blocker components. Detection is bounded to owners with at most 100 2937 unfinished tasks. This endpoint is read-only: cycles do not prevent task 2938 updates, lease acquisition, or completion. 2939 2940 Args: 2941 user: User ID (`usr_...`) for user-scoped tasks. 2942 team: Team ID (`tem_...`) owning the tasks. 2943 org: Optional organization context for privileged callers. 2944 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 2945 after_cursor: Opaque cursor returned by the preceding page. 2946 2947 Returns: 2948 Successful response 2949 """ 2950 query: dict[str, object] = {} 2951 if team is not None: 2952 query["team"] = team 2953 if org is not None: 2954 query["org"] = org 2955 if limit is not None: 2956 query["limit"] = limit 2957 if after_cursor is not None: 2958 query["after_cursor"] = after_cursor 2959 return await self._http.request( 2960 f"/api/v1/users/{user}/tasks/blocker_cycles", 2961 query=query, 2962 response_type=UserTaskBlockerCyclesResponse, 2963 ) 2964 2965 async def ready( 2966 self, 2967 user: str, 2968 *, 2969 team: str | None = None, 2970 org: str | None = None, 2971 explain: bool | None = None, 2972 assigned_to_me: bool | None = None, 2973 source_scope: str | None = None, 2974 source_type: str | None = None, 2975 source_id: str | None = None, 2976 epic: str | None = None, 2977 limit: int | None = None, 2978 after_cursor: str | None = None, 2979 ) -> UserTaskReadyResponse: 2980 """ 2981 List an owner's ready tasks 2982 Returns open tasks with no unfinished blockers and no active session lease. 2983 Readiness is calculated by the server from the current task projection. It is 2984 a snapshot, not a reservation; claim a task lease before starting work. 2985 Pass `explain=true` to include every open task with a stable readiness reason. 2986 2987 Args: 2988 user: User ID (`usr_...`) for user-scoped tasks. 2989 team: Team ID (`tem_...`) owning the tasks. 2990 org: Optional organization context for privileged callers. 2991 explain: Include blocked and actively leased open tasks with exclusion reasons. 2992 assigned_to_me: Only include tasks assigned to the authenticated user. 2993 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 2994 source_type: Only include tasks whose source matches this object kind. 2995 source_id: Only include tasks whose source matches this object identity. 2996 epic: Only include tasks with this exact epic label. 2997 limit: Maximum number of readiness entries to return. Capped at 100. 2998 after_cursor: Opaque cursor returned by the previous page. 2999 3000 Returns: 3001 Successful response 3002 """ 3003 query: dict[str, object] = {} 3004 if team is not None: 3005 query["team"] = team 3006 if org is not None: 3007 query["org"] = org 3008 if explain is not None: 3009 query["explain"] = explain 3010 if assigned_to_me is not None: 3011 query["assigned_to_me"] = assigned_to_me 3012 if source_scope is not None: 3013 query["source_scope"] = source_scope 3014 if source_type is not None: 3015 query["source_type"] = source_type 3016 if source_id is not None: 3017 query["source_id"] = source_id 3018 if epic is not None: 3019 query["epic"] = epic 3020 if limit is not None: 3021 query["limit"] = limit 3022 if after_cursor is not None: 3023 query["after_cursor"] = after_cursor 3024 return await self._http.request( 3025 f"/api/v1/users/{user}/tasks/ready", 3026 query=query, 3027 response_type=UserTaskReadyResponse, 3028 ) 3029 3030 async def search( 3031 self, 3032 user: str, 3033 *, 3034 team: str | None = None, 3035 org: str | None = None, 3036 q: str | None = None, 3037 query: str | None = None, 3038 status: str | None = None, 3039 owner_user: str | None = None, 3040 owner_agent: str | None = None, 3041 priority: int | None = None, 3042 tag: str | None = None, 3043 parent: str | None = None, 3044 source_scope: str | None = None, 3045 source_type: str | None = None, 3046 source_id: str | None = None, 3047 epic: str | None = None, 3048 limit: int | None = None, 3049 after_cursor: str | None = None, 3050 ) -> UserTaskSearchResponse: 3051 """ 3052 Search an owner's tasks 3053 Performs a full-text search over tasks owned by the specified user or team and returns 3054 matching results. Combine `q` with the optional filters to narrow the result set 3055 further. When no query is provided, the endpoint behaves like a filtered list. 3056 The `query` field in the response echoes the effective search query. 3057 User-authenticated callers may search their personal tasks or tasks for teams 3058 they have joined. Privileged callers provide the owner in the route; the owner's 3059 organization is implied by that principal. An explicit `org` is optional and, 3060 when set, must match the owner's organization. 3061 3062 Args: 3063 user: User ID (`usr_...`) for user-scoped tasks. 3064 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3065 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3066 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3067 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3068 status: Filter results by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to include all statuses. 3069 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3070 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3071 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3072 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3073 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3074 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3075 source_type: Return only tasks whose source matches this object kind. 3076 source_id: Return only tasks whose source matches this object identity. 3077 epic: Return only tasks with this exact epic label. 3078 limit: Maximum number of tasks to return. Capped at 100. 3079 after_cursor: Opaque cursor returned by the previous page. 3080 3081 Returns: 3082 Successful response 3083 """ 3084 query: dict[str, object] = {} 3085 if team is not None: 3086 query["team"] = team 3087 if org is not None: 3088 query["org"] = org 3089 if q is not None: 3090 query["q"] = q 3091 if query is not None: 3092 query["query"] = query 3093 if status is not None: 3094 query["status"] = status 3095 if owner_user is not None: 3096 query["owner_user"] = owner_user 3097 if owner_agent is not None: 3098 query["owner_agent"] = owner_agent 3099 if priority is not None: 3100 query["priority"] = priority 3101 if tag is not None: 3102 query["tag"] = tag 3103 if parent is not None: 3104 query["parent"] = parent 3105 if source_scope is not None: 3106 query["source_scope"] = source_scope 3107 if source_type is not None: 3108 query["source_type"] = source_type 3109 if source_id is not None: 3110 query["source_id"] = source_id 3111 if epic is not None: 3112 query["epic"] = epic 3113 if limit is not None: 3114 query["limit"] = limit 3115 if after_cursor is not None: 3116 query["after_cursor"] = after_cursor 3117 return await self._http.request( 3118 f"/api/v1/users/{user}/tasks/search", 3119 query=query, 3120 response_type=UserTaskSearchResponse, 3121 ) 3122 3123 3124class AsyncUserThreadResource: 3125 def __init__(self, http: HttpClient): 3126 self._http = http 3127 3128 async def list( 3129 self, 3130 user: str, 3131 *, 3132 agent: builtins.list[str] | None = None, 3133 filter: builtins.list[dict[str, Any]] | None = None, 3134 ) -> UserThreadListResponse: 3135 """ 3136 List threads for a user 3137 Returns all threads visible to the specified user. The authenticated caller must 3138 have access to the target user's account; a 403 is returned otherwise. 3139 Pass one or more `agent` IDs to narrow results to threads where at least one of 3140 the listed agents is also a member useful for displaying every thread a user 3141 shares with a particular agent. Pass one or more `filter` objects to narrow 3142 results by thread metadata key/value pairs. Both narrowings may be combined in 3143 a single request. 3144 Results are returned as a flat array; no cursor-based pagination is applied. 3145 Threads are ordered with default threads first, then by most recent activity 3146 (newest first), each carrying a `last_activity` timestamp. 3147 3148 Args: 3149 user: User ID (`usr_...`) whose threads should be listed. 3150 agent: Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. 3151 filter: Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata. 3152 3153 Returns: 3154 Successful response 3155 """ 3156 query: dict[str, object] = {} 3157 if agent is not None: 3158 query["agent"] = agent 3159 if filter is not None: 3160 query["filter"] = filter 3161 return await self._http.request( 3162 f"/api/v1/users/{user}/threads", 3163 query=query, 3164 response_type=UserThreadListResponse, 3165 ) 3166 3167 async def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3168 """ 3169 Create a thread for a user 3170 Creates a new thread owned by the specified user. The authenticated caller must 3171 have access to the target user's account; a 403 is returned otherwise. 3172 An automatic welcome message is sent into the thread upon creation unless 3173 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3174 the owning user and any members added at creation time. 3175 3176 Args: 3177 user: User ID (`usr_...`) whose threads should be listed. 3178 input: Request body. 3179 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3180 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3181 3182 Returns: 3183 The newly created thread object. 3184 """ 3185 return await self._http.request( 3186 f"/api/v1/users/{user}/threads", 3187 method="POST", 3188 body=input, 3189 response_type=Thread, 3190 ) 3191 3192 3193class AsyncTokenResource: 3194 def __init__(self, http: HttpClient): 3195 self._http = http 3196 3197 async def list(self, user: str) -> TokenListResponse: 3198 """ 3199 List personal access tokens 3200 Returns all access tokens associated with the authenticated user, including 3201 active and revoked tokens. Tokens are returned without their raw JWT values 3202 the plaintext JWT is only available at creation time. 3203 The caller must be the user identified by `user` and must present a 3204 first-party session (or a `full_access` access token). 3205 3206 Args: 3207 user: User ID (`usr_...`) or `me` for the authenticated user. 3208 3209 Returns: 3210 Successful response 3211 """ 3212 return await self._http.request( 3213 f"/api/v1/users/{user}/tokens", 3214 response_type=TokenListResponse, 3215 ) 3216 3217 async def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3218 """ 3219 Create a personal access token 3220 Issues a new long-lived access token for the authenticated user. The raw 3221 JWT is returned in the `token` field of the response exactly once and 3222 cannot be retrieved again store it securely immediately after creation. 3223 `scopes` is optional. When omitted the token receives `full_access`. 3224 Known catalog scopes (for example `profile`) restrict the token through 3225 the same `ScopeGuard` used by OAuth. 3226 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3227 or `365`. When omitted the token lasts 30 days. Each user may hold at 3228 most 50 active tokens; exceeding that limit returns 429. 3229 The caller must be the user identified by `user` and must present a 3230 first-party session (or a `full_access` access token). A restricted 3231 access token cannot mint another token. 3232 3233 Args: 3234 user: User ID (`usr_...`) or `me` for the authenticated user. 3235 input: Request body. 3236 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3237 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3238 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3239 3240 Returns: 3241 The newly created access token. The `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. 3242 """ 3243 return await self._http.request( 3244 f"/api/v1/users/{user}/tokens", 3245 method="POST", 3246 body=input, 3247 response_type=SystemAccessToken, 3248 ) 3249 3250 async def delete(self, user: str, token: str) -> SystemAccessToken: 3251 """ 3252 Revoke a personal access token 3253 Permanently revokes the specified access token belonging to the 3254 authenticated user. Once revoked, the token is immediately rejected by 3255 all API endpoints and cannot be reinstated. The token record is retained 3256 and returned in the response with `revoked_at` populated. 3257 The caller must be the user identified by `user` and must present a 3258 first-party session (or a `full_access` access token). Returns 404 if 3259 the token does not exist or does not belong to the caller. 3260 3261 Args: 3262 user: User ID (`usr_...`) or `me` for the authenticated user. 3263 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3264 3265 Returns: 3266 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3267 """ 3268 return await self._http.request( 3269 f"/api/v1/users/{user}/tokens/{token}", 3270 method="DELETE", 3271 response_type=SystemAccessToken, 3272 ) 3273 3274 3275class AsyncUserResource: 3276 def __init__(self, http: HttpClient): 3277 self._http = http 3278 self.tasks = AsyncUserTaskResource(http) 3279 self.threads = AsyncUserThreadResource(http) 3280 self.tokens = AsyncTokenResource(http) 3281 3282 async def me(self) -> User: 3283 """ 3284 Retrieve the current user 3285 Returns the user associated with the authenticated session or bearer 3286 token. This is the canonical way to resolve "who am I?" after 3287 authentication. 3288 The response includes the user's profile, notification settings, and 3289 profile picture, along with the app, organization, and sandbox the 3290 token is scoped to and their display names enough to establish full 3291 session context in a single call. Unauthenticated requests return 401. 3292 3293 Returns: 3294 The authenticated user object. 3295 """ 3296 return await self._http.request("/api/v1/users/me", response_type=User) 3297 3298 async def get(self, user: str) -> User: 3299 """ 3300 Retrieve a user by ID 3301 Returns the user identified by `user`. The authenticated user must share 3302 at least one team with the target user; requests for users outside any 3303 shared team are rejected with 403. 3304 A user may always retrieve their own profile with this endpoint. Use the 3305 `GET /users/me` endpoint as a convenience alias for retrieving the 3306 authenticated user without specifying an ID. 3307 3308 Args: 3309 user: User ID (`usr_...`) of the user to retrieve. 3310 3311 Returns: 3312 The requested user object. 3313 """ 3314 return await self._http.request(f"/api/v1/users/{user}", response_type=User) 3315 3316 async def artifacts(self, user: str) -> UserArtifactsResponse: 3317 """ 3318 List a user's artifacts 3319 Returns all artifacts owned by the specified user. Artifacts represent 3320 AI-generated or user-uploaded files associated with agent sessions, 3321 threads, or sandboxes such as images, documents, and code outputs. 3322 The authenticated user must be requesting their own artifacts or must 3323 have administrative access. Attempting to list artifacts for a user 3324 the caller is not authorized to access returns 403. 3325 Results are returned in a single page without cursor pagination. Each 3326 artifact in the response reflects the state of its current version, 3327 including a short-lived signed `file_url` for direct download. 3328 3329 Args: 3330 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3331 3332 Returns: 3333 Successful response 3334 """ 3335 return await self._http.request( 3336 f"/api/v1/users/{user}/artifacts", 3337 response_type=UserArtifactsResponse, 3338 ) 3339 3340 async def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3341 """ 3342 Create a user invite 3343 Creates a new invite for the authenticated user. The invite can optionally be 3344 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3345 caller receives the new invite object at HTTP 201. 3346 The invite key is always generated server-side (192-bit URL-safe random 3347 string) and cannot be supplied by the caller. 3348 The path `:user` must match the authenticated user. If a `thread_id` is 3349 provided, the authenticated user must have permission to invite others to that 3350 thread; team threads are not supported and return an error. Supplying a 3351 `thread_id` that does not exist or that belongs to a different user returns 3352 an error. If a key collision occurs during creation the call returns a 409 3353 conflict simply retry to generate a new key. 3354 3355 Args: 3356 user: User ID (`usr_...`). Must match the authenticated user. 3357 input: Request body. 3358 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3359 3360 Returns: 3361 The newly created invite object. 3362 """ 3363 return await self._http.request( 3364 f"/api/v1/users/{user}/invites", 3365 method="POST", 3366 body=input, 3367 response_type=UserInvite, 3368 ) 3369 3370 async def orgs(self, user: str) -> UserOrgsResponse: 3371 """ 3372 List organizations for a user 3373 Returns the organizations the specified user belongs to. A user can belong 3374 to at most one organization, so the `data` array contains either zero or one 3375 items. 3376 The authenticated viewer must have permission to inspect the target user. 3377 Returns an empty `data` array when the user has no organization membership. 3378 3379 Args: 3380 user: User ID (`usr_...`) whose organization membership you want to retrieve. 3381 3382 Returns: 3383 Successful response 3384 """ 3385 return await self._http.request( 3386 f"/api/v1/users/{user}/orgs", 3387 response_type=UserOrgsResponse, 3388 ) 3389 3390 async def profile(self, user: str, input: UserProfileInput) -> User: 3391 """ 3392 Update the current user's profile 3393 Updates one or more profile fields for the authenticated user. All 3394 fields are optional; omit any you do not want to change. 3395 When `profile_picture` is supplied, the image is uploaded and replaces 3396 the existing picture. The previous picture is deleted after the new one 3397 is stored. Image upload failures return 422 without modifying other 3398 profile fields. 3399 3400 Args: 3401 user: User ID (`usr_...`) or `"me"` for the authenticated user. 3402 input: Request body. 3403 input.alias: Short display alias shown in place of the full name in compact UI contexts. 3404 input.full_name: Updated display name for the user. 3405 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 3406 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 3407 3408 Returns: 3409 The user object with updated profile fields. 3410 """ 3411 return await self._http.request( 3412 f"/api/v1/users/{user}/profile", 3413 method="PUT", 3414 body=input, 3415 response_type=User, 3416 ) 3417 3418 3419class UserTaskResource: 3420 def __init__(self, http: SyncHttpClient): 3421 self._http = http 3422 3423 def list( 3424 self, 3425 user: str, 3426 *, 3427 team: str | None = None, 3428 org: str | None = None, 3429 status: str | None = None, 3430 owner_user: str | None = None, 3431 owner_agent: str | None = None, 3432 priority: int | None = None, 3433 tag: str | None = None, 3434 parent: str | None = None, 3435 source_scope: str | None = None, 3436 source_type: str | None = None, 3437 source_id: str | None = None, 3438 epic: str | None = None, 3439 search: str | None = None, 3440 sort: str | None = None, 3441 order: str | None = None, 3442 due_before: str | None = None, 3443 due_after: str | None = None, 3444 overdue: bool | None = None, 3445 ready: bool | None = None, 3446 limit: int | None = None, 3447 after_cursor: str | None = None, 3448 ) -> UserTaskListResponse: 3449 """ 3450 List an owner's tasks 3451 Returns tasks owned by the specified user or team. You can narrow results using the 3452 optional filters below. By default results are returned in reverse chronological 3453 order (most recently created first); use `sort` and `order` to sort by due date or 3454 priority instead. 3455 User-authenticated callers may list their personal tasks or tasks for teams they 3456 have joined. Privileged callers provide the owner in the route; the owner's 3457 organization is implied by that principal. An explicit `org` is optional and, 3458 when set, must match the owner's organization. 3459 3460 Args: 3461 user: User ID (`usr_...`) for user-scoped tasks. 3462 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 3463 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3464 status: Filter tasks by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to return tasks in all statuses. 3465 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3466 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3467 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3468 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3469 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3470 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3471 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3472 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3473 epic: Return only tasks with this exact epic label. 3474 search: Restrict results to tasks whose name or description contains this string. 3475 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. 3476 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3477 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. 3478 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3479 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. 3480 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. 3481 limit: Maximum number of tasks to return. Capped at 100. 3482 after_cursor: Opaque cursor returned by the previous page. 3483 3484 Returns: 3485 Successful response 3486 """ 3487 query: dict[str, object] = {} 3488 if team is not None: 3489 query["team"] = team 3490 if org is not None: 3491 query["org"] = org 3492 if status is not None: 3493 query["status"] = status 3494 if owner_user is not None: 3495 query["owner_user"] = owner_user 3496 if owner_agent is not None: 3497 query["owner_agent"] = owner_agent 3498 if priority is not None: 3499 query["priority"] = priority 3500 if tag is not None: 3501 query["tag"] = tag 3502 if parent is not None: 3503 query["parent"] = parent 3504 if source_scope is not None: 3505 query["source_scope"] = source_scope 3506 if source_type is not None: 3507 query["source_type"] = source_type 3508 if source_id is not None: 3509 query["source_id"] = source_id 3510 if epic is not None: 3511 query["epic"] = epic 3512 if search is not None: 3513 query["search"] = search 3514 if sort is not None: 3515 query["sort"] = sort 3516 if order is not None: 3517 query["order"] = order 3518 if due_before is not None: 3519 query["due_before"] = due_before 3520 if due_after is not None: 3521 query["due_after"] = due_after 3522 if overdue is not None: 3523 query["overdue"] = overdue 3524 if ready is not None: 3525 query["ready"] = ready 3526 if limit is not None: 3527 query["limit"] = limit 3528 if after_cursor is not None: 3529 query["after_cursor"] = after_cursor 3530 return self._http.request( 3531 f"/api/v1/users/{user}/tasks", 3532 query=query, 3533 response_type=UserTaskListResponse, 3534 ) 3535 3536 def create(self, user: str, input: UserTaskCreateInput) -> Task: 3537 """ 3538 Create a task for an owner 3539 Creates a new task owned by the specified user or team and returns the full 3540 task object. User-authenticated calls are attributed to the authenticated 3541 user or agent. App-scoped developer and server-to-server callers must provide 3542 the task's explicit `org` scope and an explicit `user` or `agent` actor for 3543 team tasks; a user-owned task reuses the user in the route unless an explicit 3544 agent is supplied. Every referenced principal is validated against the app, 3545 owner, and team membership before creation. 3546 3547 Args: 3548 user: User ID (`usr_...`) for user-scoped tasks. 3549 input: Request body. 3550 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 task owner. 3551 input.org: Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. 3552 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3553 input.team: Team ID (`tem_...`). The task will be owned by this team. 3554 3555 Returns: 3556 The newly created task. 3557 """ 3558 return self._http.request( 3559 f"/api/v1/users/{user}/tasks", 3560 method="POST", 3561 body=input, 3562 response_type=Task, 3563 ) 3564 3565 def blocker_cycles( 3566 self, 3567 user: str, 3568 *, 3569 team: str | None = None, 3570 org: str | None = None, 3571 limit: int | None = None, 3572 after_cursor: str | None = None, 3573 ) -> UserTaskBlockerCyclesResponse: 3574 """ 3575 List task blocker cycles 3576 Runs an on-demand diagnostic over unfinished tasks owned by the specified 3577 team or user and returns a forward cursor-paginated page of complete cyclic 3578 blocker components. Detection is bounded to owners with at most 100 3579 unfinished tasks. This endpoint is read-only: cycles do not prevent task 3580 updates, lease acquisition, or completion. 3581 3582 Args: 3583 user: User ID (`usr_...`) for user-scoped tasks. 3584 team: Team ID (`tem_...`) owning the tasks. 3585 org: Optional organization context for privileged callers. 3586 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3587 after_cursor: Opaque cursor returned by the preceding page. 3588 3589 Returns: 3590 Successful response 3591 """ 3592 query: dict[str, object] = {} 3593 if team is not None: 3594 query["team"] = team 3595 if org is not None: 3596 query["org"] = org 3597 if limit is not None: 3598 query["limit"] = limit 3599 if after_cursor is not None: 3600 query["after_cursor"] = after_cursor 3601 return self._http.request( 3602 f"/api/v1/users/{user}/tasks/blocker_cycles", 3603 query=query, 3604 response_type=UserTaskBlockerCyclesResponse, 3605 ) 3606 3607 def ready( 3608 self, 3609 user: str, 3610 *, 3611 team: str | None = None, 3612 org: str | None = None, 3613 explain: bool | None = None, 3614 assigned_to_me: bool | None = None, 3615 source_scope: str | None = None, 3616 source_type: str | None = None, 3617 source_id: str | None = None, 3618 epic: str | None = None, 3619 limit: int | None = None, 3620 after_cursor: str | None = None, 3621 ) -> UserTaskReadyResponse: 3622 """ 3623 List an owner's ready tasks 3624 Returns open tasks with no unfinished blockers and no active session lease. 3625 Readiness is calculated by the server from the current task projection. It is 3626 a snapshot, not a reservation; claim a task lease before starting work. 3627 Pass `explain=true` to include every open task with a stable readiness reason. 3628 3629 Args: 3630 user: User ID (`usr_...`) for user-scoped tasks. 3631 team: Team ID (`tem_...`) owning the tasks. 3632 org: Optional organization context for privileged callers. 3633 explain: Include blocked and actively leased open tasks with exclusion reasons. 3634 assigned_to_me: Only include tasks assigned to the authenticated user. 3635 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3636 source_type: Only include tasks whose source matches this object kind. 3637 source_id: Only include tasks whose source matches this object identity. 3638 epic: Only include tasks with this exact epic label. 3639 limit: Maximum number of readiness entries to return. Capped at 100. 3640 after_cursor: Opaque cursor returned by the previous page. 3641 3642 Returns: 3643 Successful response 3644 """ 3645 query: dict[str, object] = {} 3646 if team is not None: 3647 query["team"] = team 3648 if org is not None: 3649 query["org"] = org 3650 if explain is not None: 3651 query["explain"] = explain 3652 if assigned_to_me is not None: 3653 query["assigned_to_me"] = assigned_to_me 3654 if source_scope is not None: 3655 query["source_scope"] = source_scope 3656 if source_type is not None: 3657 query["source_type"] = source_type 3658 if source_id is not None: 3659 query["source_id"] = source_id 3660 if epic is not None: 3661 query["epic"] = epic 3662 if limit is not None: 3663 query["limit"] = limit 3664 if after_cursor is not None: 3665 query["after_cursor"] = after_cursor 3666 return self._http.request( 3667 f"/api/v1/users/{user}/tasks/ready", 3668 query=query, 3669 response_type=UserTaskReadyResponse, 3670 ) 3671 3672 def search( 3673 self, 3674 user: str, 3675 *, 3676 team: str | None = None, 3677 org: str | None = None, 3678 q: str | None = None, 3679 query: str | None = None, 3680 status: str | None = None, 3681 owner_user: str | None = None, 3682 owner_agent: str | None = None, 3683 priority: int | None = None, 3684 tag: str | None = None, 3685 parent: str | None = None, 3686 source_scope: str | None = None, 3687 source_type: str | None = None, 3688 source_id: str | None = None, 3689 epic: str | None = None, 3690 limit: int | None = None, 3691 after_cursor: str | None = None, 3692 ) -> UserTaskSearchResponse: 3693 """ 3694 Search an owner's tasks 3695 Performs a full-text search over tasks owned by the specified user or team and returns 3696 matching results. Combine `q` with the optional filters to narrow the result set 3697 further. When no query is provided, the endpoint behaves like a filtered list. 3698 The `query` field in the response echoes the effective search query. 3699 User-authenticated callers may search their personal tasks or tasks for teams 3700 they have joined. Privileged callers provide the owner in the route; the owner's 3701 organization is implied by that principal. An explicit `org` is optional and, 3702 when set, must match the owner's organization. 3703 3704 Args: 3705 user: User ID (`usr_...`) for user-scoped tasks. 3706 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3707 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3708 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3709 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3710 status: Filter results by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to include all statuses. 3711 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3712 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3713 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3714 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3715 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3716 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3717 source_type: Return only tasks whose source matches this object kind. 3718 source_id: Return only tasks whose source matches this object identity. 3719 epic: Return only tasks with this exact epic label. 3720 limit: Maximum number of tasks to return. Capped at 100. 3721 after_cursor: Opaque cursor returned by the previous page. 3722 3723 Returns: 3724 Successful response 3725 """ 3726 query: dict[str, object] = {} 3727 if team is not None: 3728 query["team"] = team 3729 if org is not None: 3730 query["org"] = org 3731 if q is not None: 3732 query["q"] = q 3733 if query is not None: 3734 query["query"] = query 3735 if status is not None: 3736 query["status"] = status 3737 if owner_user is not None: 3738 query["owner_user"] = owner_user 3739 if owner_agent is not None: 3740 query["owner_agent"] = owner_agent 3741 if priority is not None: 3742 query["priority"] = priority 3743 if tag is not None: 3744 query["tag"] = tag 3745 if parent is not None: 3746 query["parent"] = parent 3747 if source_scope is not None: 3748 query["source_scope"] = source_scope 3749 if source_type is not None: 3750 query["source_type"] = source_type 3751 if source_id is not None: 3752 query["source_id"] = source_id 3753 if epic is not None: 3754 query["epic"] = epic 3755 if limit is not None: 3756 query["limit"] = limit 3757 if after_cursor is not None: 3758 query["after_cursor"] = after_cursor 3759 return self._http.request( 3760 f"/api/v1/users/{user}/tasks/search", 3761 query=query, 3762 response_type=UserTaskSearchResponse, 3763 ) 3764 3765 3766class UserThreadResource: 3767 def __init__(self, http: SyncHttpClient): 3768 self._http = http 3769 3770 def list( 3771 self, 3772 user: str, 3773 *, 3774 agent: builtins.list[str] | None = None, 3775 filter: builtins.list[dict[str, Any]] | None = None, 3776 ) -> UserThreadListResponse: 3777 """ 3778 List threads for a user 3779 Returns all threads visible to the specified user. The authenticated caller must 3780 have access to the target user's account; a 403 is returned otherwise. 3781 Pass one or more `agent` IDs to narrow results to threads where at least one of 3782 the listed agents is also a member useful for displaying every thread a user 3783 shares with a particular agent. Pass one or more `filter` objects to narrow 3784 results by thread metadata key/value pairs. Both narrowings may be combined in 3785 a single request. 3786 Results are returned as a flat array; no cursor-based pagination is applied. 3787 Threads are ordered with default threads first, then by most recent activity 3788 (newest first), each carrying a `last_activity` timestamp. 3789 3790 Args: 3791 user: User ID (`usr_...`) whose threads should be listed. 3792 agent: Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. 3793 filter: Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata. 3794 3795 Returns: 3796 Successful response 3797 """ 3798 query: dict[str, object] = {} 3799 if agent is not None: 3800 query["agent"] = agent 3801 if filter is not None: 3802 query["filter"] = filter 3803 return self._http.request( 3804 f"/api/v1/users/{user}/threads", 3805 query=query, 3806 response_type=UserThreadListResponse, 3807 ) 3808 3809 def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3810 """ 3811 Create a thread for a user 3812 Creates a new thread owned by the specified user. The authenticated caller must 3813 have access to the target user's account; a 403 is returned otherwise. 3814 An automatic welcome message is sent into the thread upon creation unless 3815 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3816 the owning user and any members added at creation time. 3817 3818 Args: 3819 user: User ID (`usr_...`) whose threads should be listed. 3820 input: Request body. 3821 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3822 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3823 3824 Returns: 3825 The newly created thread object. 3826 """ 3827 return self._http.request( 3828 f"/api/v1/users/{user}/threads", 3829 method="POST", 3830 body=input, 3831 response_type=Thread, 3832 ) 3833 3834 3835class TokenResource: 3836 def __init__(self, http: SyncHttpClient): 3837 self._http = http 3838 3839 def list(self, user: str) -> TokenListResponse: 3840 """ 3841 List personal access tokens 3842 Returns all access tokens associated with the authenticated user, including 3843 active and revoked tokens. Tokens are returned without their raw JWT values 3844 the plaintext JWT is only available at creation time. 3845 The caller must be the user identified by `user` and must present a 3846 first-party session (or a `full_access` access token). 3847 3848 Args: 3849 user: User ID (`usr_...`) or `me` for the authenticated user. 3850 3851 Returns: 3852 Successful response 3853 """ 3854 return self._http.request(f"/api/v1/users/{user}/tokens", response_type=TokenListResponse) 3855 3856 def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3857 """ 3858 Create a personal access token 3859 Issues a new long-lived access token for the authenticated user. The raw 3860 JWT is returned in the `token` field of the response exactly once and 3861 cannot be retrieved again store it securely immediately after creation. 3862 `scopes` is optional. When omitted the token receives `full_access`. 3863 Known catalog scopes (for example `profile`) restrict the token through 3864 the same `ScopeGuard` used by OAuth. 3865 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3866 or `365`. When omitted the token lasts 30 days. Each user may hold at 3867 most 50 active tokens; exceeding that limit returns 429. 3868 The caller must be the user identified by `user` and must present a 3869 first-party session (or a `full_access` access token). A restricted 3870 access token cannot mint another token. 3871 3872 Args: 3873 user: User ID (`usr_...`) or `me` for the authenticated user. 3874 input: Request body. 3875 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3876 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3877 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3878 3879 Returns: 3880 The newly created access token. The `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. 3881 """ 3882 return self._http.request( 3883 f"/api/v1/users/{user}/tokens", 3884 method="POST", 3885 body=input, 3886 response_type=SystemAccessToken, 3887 ) 3888 3889 def delete(self, user: str, token: str) -> SystemAccessToken: 3890 """ 3891 Revoke a personal access token 3892 Permanently revokes the specified access token belonging to the 3893 authenticated user. Once revoked, the token is immediately rejected by 3894 all API endpoints and cannot be reinstated. The token record is retained 3895 and returned in the response with `revoked_at` populated. 3896 The caller must be the user identified by `user` and must present a 3897 first-party session (or a `full_access` access token). Returns 404 if 3898 the token does not exist or does not belong to the caller. 3899 3900 Args: 3901 user: User ID (`usr_...`) or `me` for the authenticated user. 3902 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3903 3904 Returns: 3905 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3906 """ 3907 return self._http.request( 3908 f"/api/v1/users/{user}/tokens/{token}", 3909 method="DELETE", 3910 response_type=SystemAccessToken, 3911 ) 3912 3913 3914class UserResource: 3915 def __init__(self, http: SyncHttpClient): 3916 self._http = http 3917 self.tasks = UserTaskResource(http) 3918 self.threads = UserThreadResource(http) 3919 self.tokens = TokenResource(http) 3920 3921 def me(self) -> User: 3922 """ 3923 Retrieve the current user 3924 Returns the user associated with the authenticated session or bearer 3925 token. This is the canonical way to resolve "who am I?" after 3926 authentication. 3927 The response includes the user's profile, notification settings, and 3928 profile picture, along with the app, organization, and sandbox the 3929 token is scoped to and their display names enough to establish full 3930 session context in a single call. Unauthenticated requests return 401. 3931 3932 Returns: 3933 The authenticated user object. 3934 """ 3935 return self._http.request("/api/v1/users/me", response_type=User) 3936 3937 def get(self, user: str) -> User: 3938 """ 3939 Retrieve a user by ID 3940 Returns the user identified by `user`. The authenticated user must share 3941 at least one team with the target user; requests for users outside any 3942 shared team are rejected with 403. 3943 A user may always retrieve their own profile with this endpoint. Use the 3944 `GET /users/me` endpoint as a convenience alias for retrieving the 3945 authenticated user without specifying an ID. 3946 3947 Args: 3948 user: User ID (`usr_...`) of the user to retrieve. 3949 3950 Returns: 3951 The requested user object. 3952 """ 3953 return self._http.request(f"/api/v1/users/{user}", response_type=User) 3954 3955 def artifacts(self, user: str) -> UserArtifactsResponse: 3956 """ 3957 List a user's artifacts 3958 Returns all artifacts owned by the specified user. Artifacts represent 3959 AI-generated or user-uploaded files associated with agent sessions, 3960 threads, or sandboxes such as images, documents, and code outputs. 3961 The authenticated user must be requesting their own artifacts or must 3962 have administrative access. Attempting to list artifacts for a user 3963 the caller is not authorized to access returns 403. 3964 Results are returned in a single page without cursor pagination. Each 3965 artifact in the response reflects the state of its current version, 3966 including a short-lived signed `file_url` for direct download. 3967 3968 Args: 3969 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3970 3971 Returns: 3972 Successful response 3973 """ 3974 return self._http.request( 3975 f"/api/v1/users/{user}/artifacts", 3976 response_type=UserArtifactsResponse, 3977 ) 3978 3979 def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3980 """ 3981 Create a user invite 3982 Creates a new invite for the authenticated user. The invite can optionally be 3983 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3984 caller receives the new invite object at HTTP 201. 3985 The invite key is always generated server-side (192-bit URL-safe random 3986 string) and cannot be supplied by the caller. 3987 The path `:user` must match the authenticated user. If a `thread_id` is 3988 provided, the authenticated user must have permission to invite others to that 3989 thread; team threads are not supported and return an error. Supplying a 3990 `thread_id` that does not exist or that belongs to a different user returns 3991 an error. If a key collision occurs during creation the call returns a 409 3992 conflict simply retry to generate a new key. 3993 3994 Args: 3995 user: User ID (`usr_...`). Must match the authenticated user. 3996 input: Request body. 3997 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3998 3999 Returns: 4000 The newly created invite object. 4001 """ 4002 return self._http.request( 4003 f"/api/v1/users/{user}/invites", 4004 method="POST", 4005 body=input, 4006 response_type=UserInvite, 4007 ) 4008 4009 def orgs(self, user: str) -> UserOrgsResponse: 4010 """ 4011 List organizations for a user 4012 Returns the organizations the specified user belongs to. A user can belong 4013 to at most one organization, so the `data` array contains either zero or one 4014 items. 4015 The authenticated viewer must have permission to inspect the target user. 4016 Returns an empty `data` array when the user has no organization membership. 4017 4018 Args: 4019 user: User ID (`usr_...`) whose organization membership you want to retrieve. 4020 4021 Returns: 4022 Successful response 4023 """ 4024 return self._http.request(f"/api/v1/users/{user}/orgs", response_type=UserOrgsResponse) 4025 4026 def profile(self, user: str, input: UserProfileInput) -> User: 4027 """ 4028 Update the current user's profile 4029 Updates one or more profile fields for the authenticated user. All 4030 fields are optional; omit any you do not want to change. 4031 When `profile_picture` is supplied, the image is uploaded and replaces 4032 the existing picture. The previous picture is deleted after the new one 4033 is stored. Image upload failures return 422 without modifying other 4034 profile fields. 4035 4036 Args: 4037 user: User ID (`usr_...`) or `"me"` for the authenticated user. 4038 input: Request body. 4039 input.alias: Short display alias shown in place of the full name in compact UI contexts. 4040 input.full_name: Updated display name for the user. 4041 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 4042 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 4043 4044 Returns: 4045 The user object with updated profile fields. 4046 """ 4047 return self._http.request( 4048 f"/api/v1/users/{user}/profile", 4049 method="PUT", 4050 body=input, 4051 response_type=User, 4052 )
class
UserTaskCreateInputTask(typing.TypedDict):
21class UserTaskCreateInputTask(TypedDict, total=False): 22 description: str | None 23 "Optional long-form description or notes for the task. Supports plain text." 24 due_date: datetime | None 25 "Date and time by which the task should be completed (ISO 8601). Omit to create the task without a due date." 26 epic: str | None 27 "Optional free-form grouping label." 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 source_id: str | None 43 "Source object identity (for example `ArchAstro/firstlanding`)." 44 source_scope: str | None 45 "Container of the work this task is about (for example `github.com`). Must be supplied with `source_type` and `source_id`." 46 source_type: str | None 47 "Kind of source object (for example `repository`)." 48 status: str | None 49 'Initial status for the task. One of `"open"`, `"in_progress"`, or `"done"`. Defaults to `"open"` when omitted.' 50 tags: list[str] | None 51 "Labels for grouping and filtering (max 20, each up to 40 characters). Stored canonically: lowercase, trimmed, de-duplicated." 52 thread: str | None 53 "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.
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.
class
UserTaskCreateInput(typing.TypedDict):
56class UserTaskCreateInput(TypedDict, total=False): 57 "Create a task for an owner" 58 59 agent: str | None 60 "Explicit acting agent (`agi_...`) for a developer or server-to-server call. Mutually exclusive with an acting `user`; the agent must belong to the task owner." 61 org: str | None 62 "Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team." 63 task: Required[UserTaskCreateInputTask] 64 "Attributes for the task to create. `name` is required; all other fields are optional." 65 team: str | None 66 "Team ID (`tem_...`). The task will be owned by this team."
Create a task for an owner
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 task owner.
org: str | None
Explicit organization (org_...) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team.
task: Required[UserTaskCreateInputTask]
Attributes for the task to create. name is required; all other fields are optional.
class
UserThreadCreateInputThreadMembersItem(typing.TypedDict):
class
UserThreadCreateInputThreadProfilePicture(typing.TypedDict):
76class UserThreadCreateInputThreadProfilePicture(TypedDict, total=False): 77 data: str | None 78 "Base64-encoded image bytes." 79 filename: str | None 80 "Original filename of the uploaded image, used for display and content-type inference." 81 mime_type: str | None 82 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.'
class
UserThreadCreateInputThreadSettings(typing.TypedDict):
85class UserThreadCreateInputThreadSettings(TypedDict, total=False): 86 agent_enabled: bool | None 87 "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
UserThreadCreateInputThread(typing.TypedDict):
90class UserThreadCreateInputThread(TypedDict, total=False): 91 create_legacy_agent: bool | None 92 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 93 description: str | None 94 "Optional longer description of the thread's purpose. `null` if not provided." 95 is_unlisted: bool | None 96 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 97 key: str | None 98 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 99 kind: Literal["personal"] | None 100 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers." 101 members: list[UserThreadCreateInputThreadMembersItem] | None 102 "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." 103 metadata: dict[str, Any] | None 104 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 105 muted: bool | None 106 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 107 org_id: str | None 108 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 109 profile_picture: UserThreadCreateInputThreadProfilePicture | None 110 "Optional profile image for the thread, provided as a base64-encoded payload." 111 settings: UserThreadCreateInputThreadSettings | None 112 "Configuration overrides for the thread, such as AI model selection and context window settings." 113 slug: str | None 114 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 115 title: str | None 116 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 117 visibility: Literal["team", "restricted", "private"] | None 118 "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."
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']]
Optional behavioral subtype. personal is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. Mirror kinds remain server-derived and cannot be selected by callers.
members: list[UserThreadCreateInputThreadMembersItem] | 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: UserThreadCreateInputThreadProfilePicture | None
Optional profile image for the thread, provided as a base64-encoded payload.
settings: UserThreadCreateInputThreadSettings | 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.
class
UserThreadCreateInput(typing.TypedDict):
121class UserThreadCreateInput(TypedDict, total=False): 122 "Create a thread for a user" 123 124 skip_welcome_message: bool | None 125 "When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`." 126 thread: Required[UserThreadCreateInputThread] 127 "Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields."
Create a thread for a user
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[UserThreadCreateInputThread]
Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields.
class
TokenCreateInput(typing.TypedDict):
130class TokenCreateInput(TypedDict, total=False): 131 "Create a personal access token" 132 133 expires_in_days: int | None 134 "Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`." 135 name: str | None 136 'Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only.' 137 scopes: list[str] | None 138 "Optional OAuth scopes to stamp on the token. Omit for `full_access`."
Create a personal access token
class
UserInvitesInputInvite(typing.TypedDict):
141class UserInvitesInputInvite(TypedDict, total=False): 142 metadata: dict[str, Any] | None 143 "Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object." 144 persona_id: str | None 145 "ID of the persona to associate with this invite (`per_...`). `null` if the invite is not bound to a persona." 146 thread_id: str | None 147 "ID of the thread to associate with this invite (`thr_...`). `null` if the invite is not bound to a thread."
metadata: dict[str, typing.Any] | None
Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object.
class
UserInvitesInput(typing.TypedDict):
150class UserInvitesInput(TypedDict): 151 "Create a user invite" 152 153 invite: UserInvitesInputInvite 154 "Parameters for the new invite. See the UserInviteCreateParams schema for field details."
Create a user invite
invite: UserInvitesInputInvite
Parameters for the new invite. See the UserInviteCreateParams schema for field details.
class
UserProfileInputProfilePicture(typing.TypedDict):
157class UserProfileInputProfilePicture(TypedDict, total=False): 158 data: str | None 159 "Base64-encoded binary content of the image file." 160 filename: str | None 161 "Original filename of the image, used for storage metadata." 162 mime_type: str | None 163 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.'
class
UserProfileInput(typing.TypedDict):
166class UserProfileInput(TypedDict, total=False): 167 "Update the current user's profile" 168 169 alias: str | None 170 "Short display alias shown in place of the full name in compact UI contexts." 171 full_name: str | None 172 "Updated display name for the user." 173 metadata: dict[str, Any] | None 174 "Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it." 175 profile_picture: UserProfileInputProfilePicture | None 176 "New profile picture to upload as a base64-encoded image. Replaces any existing picture."
Update the current user's profile
metadata: dict[str, typing.Any] | None
Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass null for a key to remove it.
profile_picture: UserProfileInputProfilePicture | None
New profile picture to upload as a base64-encoded image. Replaces any existing picture.
class
UserTaskListResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
179class UserTaskListResponseDataItemCreatedByActorProfilePicture(BaseModel): 180 file: str | None = Field( 181 default=None, 182 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 183 ) 184 height: int | None = Field( 185 default=None, description="Height of the image in pixels. `null` if not known." 186 ) 187 media: str | None = Field( 188 default=None, 189 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 190 ) 191 mime_type: str | None = Field( 192 default=None, 193 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 194 ) 195 refresh_url: str | None = Field( 196 default=None, 197 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.", 198 ) 199 url: str | None = Field( 200 default=None, 201 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.", 202 ) 203 width: int | None = Field( 204 default=None, description="Width of the image in pixels. `null` if not known." 205 )
!!! 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
UserTaskListResponseDataItemCreatedByActor(pydantic.main.BaseModel):
208class UserTaskListResponseDataItemCreatedByActor(BaseModel): 209 alias: str | None = Field( 210 default=None, 211 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 212 ) 213 id: str | None = Field( 214 default=None, 215 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 216 ) 217 name: str | None = Field( 218 default=None, 219 description="Display name of the actor shown in the UI. `null` if no name is set.", 220 ) 221 profile_picture: UserTaskListResponseDataItemCreatedByActorProfilePicture | None = Field( 222 default=None, 223 description="Profile picture for the actor. `null` if the actor has no profile picture.", 224 )
!!! 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
UserTaskListResponseDataItemCurrentLease(pydantic.main.BaseModel):
227class UserTaskListResponseDataItemCurrentLease(BaseModel): 228 expires_at: datetime = Field( 229 ..., description="Server-calculated lease expiry in ISO 8601 format." 230 ) 231 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 232 session_name: str = Field( 233 ..., description="Display name supplied by the coding session that holds the lease." 234 )
!!! 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
UserTaskListResponseDataItemOwnerActorProfilePicture(pydantic.main.BaseModel):
237class UserTaskListResponseDataItemOwnerActorProfilePicture(BaseModel): 238 file: str | None = Field( 239 default=None, 240 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 241 ) 242 height: int | None = Field( 243 default=None, description="Height of the image in pixels. `null` if not known." 244 ) 245 media: str | None = Field( 246 default=None, 247 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 248 ) 249 mime_type: str | None = Field( 250 default=None, 251 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 252 ) 253 refresh_url: str | None = Field( 254 default=None, 255 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.", 256 ) 257 url: str | None = Field( 258 default=None, 259 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.", 260 ) 261 width: int | None = Field( 262 default=None, description="Width of the image in pixels. `null` if not known." 263 )
!!! 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
UserTaskListResponseDataItemOwnerActor(pydantic.main.BaseModel):
266class UserTaskListResponseDataItemOwnerActor(BaseModel): 267 alias: str | None = Field( 268 default=None, 269 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 270 ) 271 id: str | None = Field( 272 default=None, 273 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 274 ) 275 name: str | None = Field( 276 default=None, 277 description="Display name of the actor shown in the UI. `null` if no name is set.", 278 ) 279 profile_picture: UserTaskListResponseDataItemOwnerActorProfilePicture | None = Field( 280 default=None, 281 description="Profile picture for the actor. `null` if the actor has no profile picture.", 282 )
!!! 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
UserTaskListResponseDataItem(pydantic.main.BaseModel):
285class UserTaskListResponseDataItem(BaseModel): 286 agent: str | None = Field( 287 default=None, 288 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 289 ) 290 blocked_by_count: int | None = Field( 291 default=None, 292 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 293 ) 294 closed_at: datetime | None = Field( 295 default=None, 296 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 297 ) 298 comments_count: int | None = Field( 299 default=None, description="Total number of comments posted on this task." 300 ) 301 created_at: datetime | None = Field( 302 default=None, description="When the task was created (ISO 8601)." 303 ) 304 created_by_actor: UserTaskListResponseDataItemCreatedByActor | None = Field( 305 default=None, 306 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).", 307 ) 308 created_by_agent: str | None = Field( 309 default=None, 310 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.", 311 ) 312 created_by_user: str | None = Field( 313 default=None, 314 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.", 315 ) 316 current_lease: UserTaskListResponseDataItemCurrentLease | None = Field( 317 default=None, 318 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.", 319 ) 320 description: str | None = Field( 321 default=None, 322 description="Long-form description or notes for the task. `null` if no description has been provided.", 323 ) 324 due_date: datetime | None = Field( 325 default=None, 326 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 327 ) 328 epic: str | None = Field( 329 default=None, 330 description="Free-form grouping label. `null` when the task is not in an epic.", 331 ) 332 id: str = Field(..., description="Task ID (`tsk_...`).") 333 is_blocked: bool | None = Field( 334 default=None, 335 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 336 ) 337 links: dict[str, Any] | None = Field( 338 default=None, 339 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 340 ) 341 metadata: dict[str, Any] | None = Field( 342 default=None, 343 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 344 ) 345 name: str = Field(..., description="Human-readable title of the task.") 346 org: str | None = Field( 347 default=None, 348 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 349 ) 350 owner_actor: UserTaskListResponseDataItemOwnerActor | None = Field( 351 default=None, 352 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).", 353 ) 354 owner_agent: str | None = Field( 355 default=None, 356 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.", 357 ) 358 owner_user: str | None = Field( 359 default=None, 360 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.", 361 ) 362 parent: str | None = Field( 363 default=None, 364 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 365 ) 366 priority: int | None = Field( 367 default=None, 368 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 369 ) 370 sandbox: str | None = Field( 371 default=None, 372 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 373 ) 374 source_id: str | None = Field( 375 default=None, 376 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 377 ) 378 source_scope: str | None = Field( 379 default=None, 380 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`.", 381 ) 382 source_type: str | None = Field( 383 default=None, 384 description="Kind of source object (for example `repository`). `null` when the task has no source.", 385 ) 386 status: str = Field( 387 ..., 388 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 389 ) 390 subtasks_count: int | None = Field( 391 default=None, 392 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 393 ) 394 tags: list[str] | None = Field( 395 default=None, 396 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 397 ) 398 team: str | None = Field( 399 default=None, 400 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 401 ) 402 thread: str | None = Field( 403 default=None, 404 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.", 405 ) 406 updated_at: datetime | None = Field( 407 default=None, description="When the task was last modified (ISO 8601)." 408 ) 409 user: str | None = Field( 410 default=None, 411 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 412 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
blocked_by_count: int | None =
None
Number of tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report false until the next read.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", or "done".
subtasks_count: int | None =
None
Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskListResponse(pydantic.main.BaseModel):
415class UserTaskListResponse(BaseModel): 416 """ 417 Successful response 418 """ 419 420 after_cursor: str | None = None 421 before_cursor: str | None = None 422 data: list[UserTaskListResponseDataItem] = Field( 423 ..., description="Array of task objects matching the requested filters." 424 ) 425 has_more: bool
Successful response
class
UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
428class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture(BaseModel): 429 file: str | None = Field( 430 default=None, 431 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 432 ) 433 height: int | None = Field( 434 default=None, description="Height of the image in pixels. `null` if not known." 435 ) 436 media: str | None = Field( 437 default=None, 438 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 439 ) 440 mime_type: str | None = Field( 441 default=None, 442 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 443 ) 444 refresh_url: str | None = Field( 445 default=None, 446 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.", 447 ) 448 url: str | None = Field( 449 default=None, 450 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.", 451 ) 452 width: int | None = Field( 453 default=None, description="Width of the image in pixels. `null` if not known." 454 )
!!! 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
UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(pydantic.main.BaseModel):
457class UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor(BaseModel): 458 alias: str | None = Field( 459 default=None, 460 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 461 ) 462 id: str | None = Field( 463 default=None, 464 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 465 ) 466 name: str | None = Field( 467 default=None, 468 description="Display name of the actor shown in the UI. `null` if no name is set.", 469 ) 470 profile_picture: ( 471 UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None 472 ) = Field( 473 default=None, 474 description="Profile picture for the actor. `null` if the actor has no profile picture.", 475 )
!!! 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: UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActorProfilePicture | None =
None
Profile picture for the actor. null if the actor has no profile picture.
class
UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(pydantic.main.BaseModel):
478class UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease(BaseModel): 479 expires_at: datetime = Field( 480 ..., description="Server-calculated lease expiry in ISO 8601 format." 481 ) 482 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 483 session_name: str = Field( 484 ..., description="Display name supplied by the coding session that holds the lease." 485 )
!!! 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
UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(pydantic.main.BaseModel):
488class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture(BaseModel): 489 file: str | None = Field( 490 default=None, 491 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 492 ) 493 height: int | None = Field( 494 default=None, description="Height of the image in pixels. `null` if not known." 495 ) 496 media: str | None = Field( 497 default=None, 498 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 499 ) 500 mime_type: str | None = Field( 501 default=None, 502 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 503 ) 504 refresh_url: str | None = Field( 505 default=None, 506 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.", 507 ) 508 url: str | None = Field( 509 default=None, 510 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.", 511 ) 512 width: int | None = Field( 513 default=None, description="Width of the image in pixels. `null` if not known." 514 )
!!! 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
UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(pydantic.main.BaseModel):
517class UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor(BaseModel): 518 alias: str | None = Field( 519 default=None, 520 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 521 ) 522 id: str | None = Field( 523 default=None, 524 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 525 ) 526 name: str | None = Field( 527 default=None, 528 description="Display name of the actor shown in the UI. `null` if no name is set.", 529 ) 530 profile_picture: ( 531 UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None 532 ) = Field( 533 default=None, 534 description="Profile picture for the actor. `null` if the actor has no profile picture.", 535 )
!!! 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: UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActorProfilePicture | None =
None
Profile picture for the actor. null if the actor has no profile picture.
class
UserTaskBlockerCyclesResponseDataItemTasksItem(pydantic.main.BaseModel):
538class UserTaskBlockerCyclesResponseDataItemTasksItem(BaseModel): 539 agent: str | None = Field( 540 default=None, 541 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 542 ) 543 blocked_by_count: int | None = Field( 544 default=None, 545 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 546 ) 547 closed_at: datetime | None = Field( 548 default=None, 549 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 550 ) 551 comments_count: int | None = Field( 552 default=None, description="Total number of comments posted on this task." 553 ) 554 created_at: datetime | None = Field( 555 default=None, description="When the task was created (ISO 8601)." 556 ) 557 created_by_actor: UserTaskBlockerCyclesResponseDataItemTasksItemCreatedByActor | None = Field( 558 default=None, 559 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).", 560 ) 561 created_by_agent: str | None = Field( 562 default=None, 563 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.", 564 ) 565 created_by_user: str | None = Field( 566 default=None, 567 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.", 568 ) 569 current_lease: UserTaskBlockerCyclesResponseDataItemTasksItemCurrentLease | None = Field( 570 default=None, 571 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.", 572 ) 573 description: str | None = Field( 574 default=None, 575 description="Long-form description or notes for the task. `null` if no description has been provided.", 576 ) 577 due_date: datetime | None = Field( 578 default=None, 579 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 580 ) 581 epic: str | None = Field( 582 default=None, 583 description="Free-form grouping label. `null` when the task is not in an epic.", 584 ) 585 id: str = Field(..., description="Task ID (`tsk_...`).") 586 is_blocked: bool | None = Field( 587 default=None, 588 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 589 ) 590 links: dict[str, Any] | None = Field( 591 default=None, 592 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 593 ) 594 metadata: dict[str, Any] | None = Field( 595 default=None, 596 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 597 ) 598 name: str = Field(..., description="Human-readable title of the task.") 599 org: str | None = Field( 600 default=None, 601 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 602 ) 603 owner_actor: UserTaskBlockerCyclesResponseDataItemTasksItemOwnerActor | None = Field( 604 default=None, 605 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).", 606 ) 607 owner_agent: str | None = Field( 608 default=None, 609 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.", 610 ) 611 owner_user: str | None = Field( 612 default=None, 613 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.", 614 ) 615 parent: str | None = Field( 616 default=None, 617 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 618 ) 619 priority: int | None = Field( 620 default=None, 621 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 622 ) 623 sandbox: str | None = Field( 624 default=None, 625 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 626 ) 627 source_id: str | None = Field( 628 default=None, 629 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 630 ) 631 source_scope: str | None = Field( 632 default=None, 633 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`.", 634 ) 635 source_type: str | None = Field( 636 default=None, 637 description="Kind of source object (for example `repository`). `null` when the task has no source.", 638 ) 639 status: str = Field( 640 ..., 641 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 642 ) 643 subtasks_count: int | None = Field( 644 default=None, 645 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 646 ) 647 tags: list[str] | None = Field( 648 default=None, 649 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 650 ) 651 team: str | None = Field( 652 default=None, 653 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 654 ) 655 thread: str | None = Field( 656 default=None, 657 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.", 658 ) 659 updated_at: datetime | None = Field( 660 default=None, description="When the task was last modified (ISO 8601)." 661 ) 662 user: str | None = Field( 663 default=None, 664 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 665 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
blocked_by_count: int | None =
None
Number of tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report false until the next read.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", or "done".
subtasks_count: int | None =
None
Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskBlockerCyclesResponseDataItem(pydantic.main.BaseModel):
668class UserTaskBlockerCyclesResponseDataItem(BaseModel): 669 tasks: list[UserTaskBlockerCyclesResponseDataItemTasksItem] = Field( 670 ..., description="Every unfinished task in this cyclic blocker component." 671 )
!!! 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
UserTaskBlockerCyclesResponse(pydantic.main.BaseModel):
674class UserTaskBlockerCyclesResponse(BaseModel): 675 """ 676 Successful response 677 """ 678 679 after_cursor: str | None = None 680 before_cursor: str | None = None 681 data: list[UserTaskBlockerCyclesResponseDataItem] 682 has_more: bool
Successful response
class
UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(pydantic.main.BaseModel):
685class UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture(BaseModel): 686 file: str | None = Field( 687 default=None, 688 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 689 ) 690 height: int | None = Field( 691 default=None, description="Height of the image in pixels. `null` if not known." 692 ) 693 media: str | None = Field( 694 default=None, 695 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 696 ) 697 mime_type: str | None = Field( 698 default=None, 699 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 700 ) 701 refresh_url: str | None = Field( 702 default=None, 703 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.", 704 ) 705 url: str | None = Field( 706 default=None, 707 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.", 708 ) 709 width: int | None = Field( 710 default=None, description="Width of the image in pixels. `null` if not known." 711 )
!!! 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
UserTaskReadyResponseDataItemTaskCreatedByActor(pydantic.main.BaseModel):
714class UserTaskReadyResponseDataItemTaskCreatedByActor(BaseModel): 715 alias: str | None = Field( 716 default=None, 717 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 718 ) 719 id: str | None = Field( 720 default=None, 721 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 722 ) 723 name: str | None = Field( 724 default=None, 725 description="Display name of the actor shown in the UI. `null` if no name is set.", 726 ) 727 profile_picture: UserTaskReadyResponseDataItemTaskCreatedByActorProfilePicture | None = Field( 728 default=None, 729 description="Profile picture for the actor. `null` if the actor has no profile picture.", 730 )
!!! 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
UserTaskReadyResponseDataItemTaskCurrentLease(pydantic.main.BaseModel):
733class UserTaskReadyResponseDataItemTaskCurrentLease(BaseModel): 734 expires_at: datetime = Field( 735 ..., description="Server-calculated lease expiry in ISO 8601 format." 736 ) 737 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 738 session_name: str = Field( 739 ..., description="Display name supplied by the coding session that holds the lease." 740 )
!!! 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
UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture(pydantic.main.BaseModel):
743class UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture(BaseModel): 744 file: str | None = Field( 745 default=None, 746 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 747 ) 748 height: int | None = Field( 749 default=None, description="Height of the image in pixels. `null` if not known." 750 ) 751 media: str | None = Field( 752 default=None, 753 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 754 ) 755 mime_type: str | None = Field( 756 default=None, 757 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 758 ) 759 refresh_url: str | None = Field( 760 default=None, 761 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.", 762 ) 763 url: str | None = Field( 764 default=None, 765 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.", 766 ) 767 width: int | None = Field( 768 default=None, description="Width of the image in pixels. `null` if not known." 769 )
!!! 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
UserTaskReadyResponseDataItemTaskOwnerActor(pydantic.main.BaseModel):
772class UserTaskReadyResponseDataItemTaskOwnerActor(BaseModel): 773 alias: str | None = Field( 774 default=None, 775 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 776 ) 777 id: str | None = Field( 778 default=None, 779 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 780 ) 781 name: str | None = Field( 782 default=None, 783 description="Display name of the actor shown in the UI. `null` if no name is set.", 784 ) 785 profile_picture: UserTaskReadyResponseDataItemTaskOwnerActorProfilePicture | None = Field( 786 default=None, 787 description="Profile picture for the actor. `null` if the actor has no profile picture.", 788 )
!!! 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
UserTaskReadyResponseDataItemTask(pydantic.main.BaseModel):
791class UserTaskReadyResponseDataItemTask(BaseModel): 792 agent: str | None = Field( 793 default=None, 794 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 795 ) 796 blocked_by_count: int | None = Field( 797 default=None, 798 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 799 ) 800 closed_at: datetime | None = Field( 801 default=None, 802 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 803 ) 804 comments_count: int | None = Field( 805 default=None, description="Total number of comments posted on this task." 806 ) 807 created_at: datetime | None = Field( 808 default=None, description="When the task was created (ISO 8601)." 809 ) 810 created_by_actor: UserTaskReadyResponseDataItemTaskCreatedByActor | None = Field( 811 default=None, 812 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).", 813 ) 814 created_by_agent: str | None = Field( 815 default=None, 816 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.", 817 ) 818 created_by_user: str | None = Field( 819 default=None, 820 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.", 821 ) 822 current_lease: UserTaskReadyResponseDataItemTaskCurrentLease | None = Field( 823 default=None, 824 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.", 825 ) 826 description: str | None = Field( 827 default=None, 828 description="Long-form description or notes for the task. `null` if no description has been provided.", 829 ) 830 due_date: datetime | None = Field( 831 default=None, 832 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 833 ) 834 epic: str | None = Field( 835 default=None, 836 description="Free-form grouping label. `null` when the task is not in an epic.", 837 ) 838 id: str = Field(..., description="Task ID (`tsk_...`).") 839 is_blocked: bool | None = Field( 840 default=None, 841 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 842 ) 843 links: dict[str, Any] | None = Field( 844 default=None, 845 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 846 ) 847 metadata: dict[str, Any] | None = Field( 848 default=None, 849 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 850 ) 851 name: str = Field(..., description="Human-readable title of the task.") 852 org: str | None = Field( 853 default=None, 854 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 855 ) 856 owner_actor: UserTaskReadyResponseDataItemTaskOwnerActor | None = Field( 857 default=None, 858 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).", 859 ) 860 owner_agent: str | None = Field( 861 default=None, 862 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.", 863 ) 864 owner_user: str | None = Field( 865 default=None, 866 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.", 867 ) 868 parent: str | None = Field( 869 default=None, 870 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 871 ) 872 priority: int | None = Field( 873 default=None, 874 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 875 ) 876 sandbox: str | None = Field( 877 default=None, 878 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 879 ) 880 source_id: str | None = Field( 881 default=None, 882 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 883 ) 884 source_scope: str | None = Field( 885 default=None, 886 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`.", 887 ) 888 source_type: str | None = Field( 889 default=None, 890 description="Kind of source object (for example `repository`). `null` when the task has no source.", 891 ) 892 status: str = Field( 893 ..., 894 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 895 ) 896 subtasks_count: int | None = Field( 897 default=None, 898 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 899 ) 900 tags: list[str] | None = Field( 901 default=None, 902 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 903 ) 904 team: str | None = Field( 905 default=None, 906 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 907 ) 908 thread: str | None = Field( 909 default=None, 910 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.", 911 ) 912 updated_at: datetime | None = Field( 913 default=None, description="When the task was last modified (ISO 8601)." 914 ) 915 user: str | None = Field( 916 default=None, 917 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 918 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
blocked_by_count: int | None =
None
Number of tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report false until the next read.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", or "done".
subtasks_count: int | None =
None
Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskReadyResponseDataItem(pydantic.main.BaseModel):
921class UserTaskReadyResponseDataItem(BaseModel): 922 readiness: Literal["ready", "blocked", "leased"] = Field( 923 ..., description="One of `ready`, `blocked`, or `leased`." 924 ) 925 reason: Literal["open_blockers", "active_lease"] | None = Field( 926 default=None, 927 description="Stable exclusion reason: `open_blockers` or `active_lease`; omitted when ready.", 928 ) 929 task: UserTaskReadyResponseDataItemTask = Field( 930 ..., description="The task evaluated for readiness." 931 )
!!! 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
UserTaskReadyResponse(pydantic.main.BaseModel):
934class UserTaskReadyResponse(BaseModel): 935 """ 936 Successful response 937 """ 938 939 after_cursor: str | None = None 940 authoritative: bool = Field( 941 ..., 942 description="Always false because projections can lag writes and a later claim can race this read.", 943 ) 944 before_cursor: str | None = None 945 data: list[UserTaskReadyResponseDataItem] 946 has_more: bool
Successful response
class
UserTaskSearchResponseDataItemCreatedByActorProfilePicture(pydantic.main.BaseModel):
949class UserTaskSearchResponseDataItemCreatedByActorProfilePicture(BaseModel): 950 file: str | None = Field( 951 default=None, 952 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 953 ) 954 height: int | None = Field( 955 default=None, description="Height of the image in pixels. `null` if not known." 956 ) 957 media: str | None = Field( 958 default=None, 959 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 960 ) 961 mime_type: str | None = Field( 962 default=None, 963 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 964 ) 965 refresh_url: str | None = Field( 966 default=None, 967 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.", 968 ) 969 url: str | None = Field( 970 default=None, 971 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.", 972 ) 973 width: int | None = Field( 974 default=None, description="Width of the image in pixels. `null` if not known." 975 )
!!! 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
UserTaskSearchResponseDataItemCreatedByActor(pydantic.main.BaseModel):
978class UserTaskSearchResponseDataItemCreatedByActor(BaseModel): 979 alias: str | None = Field( 980 default=None, 981 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 982 ) 983 id: str | None = Field( 984 default=None, 985 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 986 ) 987 name: str | None = Field( 988 default=None, 989 description="Display name of the actor shown in the UI. `null` if no name is set.", 990 ) 991 profile_picture: UserTaskSearchResponseDataItemCreatedByActorProfilePicture | None = Field( 992 default=None, 993 description="Profile picture for the actor. `null` if the actor has no profile picture.", 994 )
!!! 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
UserTaskSearchResponseDataItemCurrentLease(pydantic.main.BaseModel):
997class UserTaskSearchResponseDataItemCurrentLease(BaseModel): 998 expires_at: datetime = Field( 999 ..., description="Server-calculated lease expiry in ISO 8601 format." 1000 ) 1001 harness: str = Field(..., description="Bounded harness identifier for the coding session.") 1002 session_name: str = Field( 1003 ..., description="Display name supplied by the coding session that holds the lease." 1004 )
!!! 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
UserTaskSearchResponseDataItemOwnerActorProfilePicture(pydantic.main.BaseModel):
1007class UserTaskSearchResponseDataItemOwnerActorProfilePicture(BaseModel): 1008 file: str | None = Field( 1009 default=None, 1010 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1011 ) 1012 height: int | None = Field( 1013 default=None, description="Height of the image in pixels. `null` if not known." 1014 ) 1015 media: str | None = Field( 1016 default=None, 1017 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1018 ) 1019 mime_type: str | None = Field( 1020 default=None, 1021 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1022 ) 1023 refresh_url: str | None = Field( 1024 default=None, 1025 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.", 1026 ) 1027 url: str | None = Field( 1028 default=None, 1029 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.", 1030 ) 1031 width: int | None = Field( 1032 default=None, description="Width of the image in pixels. `null` if not known." 1033 )
!!! 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
UserTaskSearchResponseDataItemOwnerActor(pydantic.main.BaseModel):
1036class UserTaskSearchResponseDataItemOwnerActor(BaseModel): 1037 alias: str | None = Field( 1038 default=None, 1039 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1040 ) 1041 id: str | None = Field( 1042 default=None, 1043 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1044 ) 1045 name: str | None = Field( 1046 default=None, 1047 description="Display name of the actor shown in the UI. `null` if no name is set.", 1048 ) 1049 profile_picture: UserTaskSearchResponseDataItemOwnerActorProfilePicture | None = Field( 1050 default=None, 1051 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1052 )
!!! 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
UserTaskSearchResponseDataItem(pydantic.main.BaseModel):
1055class UserTaskSearchResponseDataItem(BaseModel): 1056 agent: str | None = Field( 1057 default=None, 1058 description="ID of the agent that owns this task (`agi_...`). `null` if the task is scoped to a team or user.", 1059 ) 1060 blocked_by_count: int | None = Field( 1061 default=None, 1062 description="Number of tasks marked as blocking this task, whether or not they are done (see `GET /tasks/{task}/blockers`). Computed on list/show reads; create/update responses may lag one read behind.", 1063 ) 1064 closed_at: datetime | None = Field( 1065 default=None, 1066 description="When the task was marked as done or otherwise closed (ISO 8601). `null` if the task is still open.", 1067 ) 1068 comments_count: int | None = Field( 1069 default=None, description="Total number of comments posted on this task." 1070 ) 1071 created_at: datetime | None = Field( 1072 default=None, description="When the task was created (ISO 8601)." 1073 ) 1074 created_by_actor: UserTaskSearchResponseDataItemCreatedByActor | None = Field( 1075 default=None, 1076 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).", 1077 ) 1078 created_by_agent: str | None = Field( 1079 default=None, 1080 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.", 1081 ) 1082 created_by_user: str | None = Field( 1083 default=None, 1084 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.", 1085 ) 1086 current_lease: UserTaskSearchResponseDataItemCurrentLease | None = Field( 1087 default=None, 1088 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.", 1089 ) 1090 description: str | None = Field( 1091 default=None, 1092 description="Long-form description or notes for the task. `null` if no description has been provided.", 1093 ) 1094 due_date: datetime | None = Field( 1095 default=None, 1096 description="Date and time by which the task should be completed (ISO 8601). `null` if no due date is set.", 1097 ) 1098 epic: str | None = Field( 1099 default=None, 1100 description="Free-form grouping label. `null` when the task is not in an epic.", 1101 ) 1102 id: str = Field(..., description="Task ID (`tsk_...`).") 1103 is_blocked: bool | None = Field( 1104 default=None, 1105 description="`true` while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report `false` until the next read.", 1106 ) 1107 links: dict[str, Any] | None = Field( 1108 default=None, 1109 description="Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.", 1110 ) 1111 metadata: dict[str, Any] | None = Field( 1112 default=None, 1113 description="Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.", 1114 ) 1115 name: str = Field(..., description="Human-readable title of the task.") 1116 org: str | None = Field( 1117 default=None, 1118 description="ID of the organization this task belongs to (`org_...`). `null` for tasks outside an org context.", 1119 ) 1120 owner_actor: UserTaskSearchResponseDataItemOwnerActor | None = Field( 1121 default=None, 1122 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).", 1123 ) 1124 owner_agent: str | None = Field( 1125 default=None, 1126 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.", 1127 ) 1128 owner_user: str | None = Field( 1129 default=None, 1130 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.", 1131 ) 1132 parent: str | None = Field( 1133 default=None, 1134 description="ID of the parent task when this task is a subtask (`tsk_...`). `null` for top-level tasks. Subtasks nest exactly one level.", 1135 ) 1136 priority: int | None = Field( 1137 default=None, 1138 description="Priority level of the task from `0` (highest) to `4` (lowest). Defaults to `2` (medium) when not explicitly set.", 1139 ) 1140 sandbox: str | None = Field( 1141 default=None, 1142 description="ID of the developer sandbox this task is scoped to (`dsb_...`). `null` for tasks outside a sandbox environment.", 1143 ) 1144 source_id: str | None = Field( 1145 default=None, 1146 description="Source object identity (for example `ArchAstro/firstlanding`). `null` when the task has no source.", 1147 ) 1148 source_scope: str | None = Field( 1149 default=None, 1150 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`.", 1151 ) 1152 source_type: str | None = Field( 1153 default=None, 1154 description="Kind of source object (for example `repository`). `null` when the task has no source.", 1155 ) 1156 status: str = Field( 1157 ..., 1158 description='Current status of the task. One of `"open"`, `"in_progress"`, or `"done"`.', 1159 ) 1160 subtasks_count: int | None = Field( 1161 default=None, 1162 description="Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.", 1163 ) 1164 tags: list[str] | None = Field( 1165 default=None, 1166 description="Labels for grouping and filtering, stored lowercase and de-duplicated. Empty array when untagged.", 1167 ) 1168 team: str | None = Field( 1169 default=None, 1170 description="ID of the team that owns this task (`tem_...`). `null` if the task is not scoped to a team.", 1171 ) 1172 thread: str | None = Field( 1173 default=None, 1174 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.", 1175 ) 1176 updated_at: datetime | None = Field( 1177 default=None, description="When the task was last modified (ISO 8601)." 1178 ) 1179 user: str | None = Field( 1180 default=None, 1181 description="ID of the user that owns this task (`usr_...`). `null` if the task is scoped to a team.", 1182 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
ID of the agent that owns this task (agi_...). null if the task is scoped to a team or user.
blocked_by_count: int | None =
None
Number of tasks marked as blocking this task, whether or not they are done (see GET /tasks/{task}/blockers). Computed on list/show reads; create/update responses may lag one read behind.
closed_at: datetime.datetime | None =
None
When the task was marked as done or otherwise closed (ISO 8601). null if the task is still open.
created_by_agent: str | None =
None
ID of the agent that created this task (agi_...). null if the task was created by a human user, or if the creating agent was later deleted.
created_by_user: str | None =
None
ID of the user who created this task (usr_...). null if the task was created by an agent, or if creator provenance was cleared after the creator was deleted.
Viewer-safe live coding-session lease summary. null when the task is unleased or the projected lease has expired. Fencing identifiers are never included.
description: str | None =
None
Long-form description or notes for the task. null if no description has been provided.
due_date: datetime.datetime | None =
None
Date and time by which the task should be completed (ISO 8601). null if no due date is set.
is_blocked: bool | None =
None
true while at least one blocking task is not yet done. Informational only a blocked task can still change status and derived at read time, so the task un-blocks automatically when its last open blocker completes. Computed on list/show reads; create/update responses report false until the next read.
links: dict[str, typing.Any] | None =
None
Key-value map of named URLs or references associated with the task. Returns an empty object when no links have been set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value map of application-specific data stored alongside the task. Returns an empty object when no metadata has been set.
org: str | None =
None
ID of the organization this task belongs to (org_...). null for tasks outside an org context.
owner_agent: str | None =
None
ID of the agent assigned as owner (agi_...). null if the owner is a human user, the task is unassigned, or the assigned agent was deleted.
owner_user: str | None =
None
ID of the user assigned as owner (usr_...). null if the owner is an agent, the task is unassigned, or the assigned agent was deleted.
parent: str | None =
None
ID of the parent task when this task is a subtask (tsk_...). null for top-level tasks. Subtasks nest exactly one level.
priority: int | None =
None
Priority level of the task from 0 (highest) to 4 (lowest). Defaults to 2 (medium) when not explicitly set.
sandbox: str | None =
None
ID of the developer sandbox this task is scoped to (dsb_...). null for tasks outside a sandbox environment.
source_id: str | None =
None
Source object identity (for example ArchAstro/firstlanding). null when the task has no source.
source_scope: str | None =
None
Container of the work this task is about (for example github.com). null when the task has no source. Set together with source_type and source_id.
source_type: str | None =
None
Kind of source object (for example repository). null when the task has no source.
status: str =
PydanticUndefined
Current status of the task. One of "open", "in_progress", or "done".
subtasks_count: int | None =
None
Number of subtasks under this task. Computed on list/show reads; create/update responses may report 0 until the next read. Always 0 for subtasks.
team: str | None =
None
ID of the team that owns this task (tem_...). null if the task is not scoped to a team.
class
UserTaskSearchResponse(pydantic.main.BaseModel):
1185class UserTaskSearchResponse(BaseModel): 1186 """ 1187 Successful response 1188 """ 1189 1190 after_cursor: str | None = None 1191 before_cursor: str | None = None 1192 data: list[UserTaskSearchResponseDataItem] = Field( 1193 ..., description="Array of task objects matching the query and filters." 1194 ) 1195 has_more: bool 1196 query: str
Successful response
class
UserThreadListResponseDataItemParentMessageAclAddItem(pydantic.main.BaseModel):
1199class UserThreadListResponseDataItemParentMessageAclAddItem(BaseModel): 1200 actions: list[str] = Field( 1201 ..., 1202 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1203 ) 1204 principal: str | None = Field( 1205 default=None, 1206 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"`.', 1207 ) 1208 principal_type: str = Field( 1209 ..., 1210 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1211 )
!!! 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
UserThreadListResponseDataItemParentMessageAclGrantsItem(pydantic.main.BaseModel):
1214class UserThreadListResponseDataItemParentMessageAclGrantsItem(BaseModel): 1215 actions: list[str] = Field( 1216 ..., 1217 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1218 ) 1219 principal: str | None = Field( 1220 default=None, 1221 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"`.', 1222 ) 1223 principal_type: str = Field( 1224 ..., 1225 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1226 )
!!! 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
UserThreadListResponseDataItemParentMessageAclRemoveItem(pydantic.main.BaseModel):
1229class UserThreadListResponseDataItemParentMessageAclRemoveItem(BaseModel): 1230 principal: str | None = Field( 1231 default=None, 1232 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"`.', 1233 ) 1234 principal_type: str = Field( 1235 ..., 1236 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1237 )
!!! 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
UserThreadListResponseDataItemParentMessageAcl(pydantic.main.BaseModel):
1240class UserThreadListResponseDataItemParentMessageAcl(BaseModel): 1241 add: list[UserThreadListResponseDataItemParentMessageAclAddItem] | None = Field( 1242 default=None, 1243 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1244 ) 1245 grants: list[UserThreadListResponseDataItemParentMessageAclGrantsItem] | None = Field( 1246 default=None, 1247 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`.", 1248 ) 1249 remove: list[UserThreadListResponseDataItemParentMessageAclRemoveItem] | None = Field( 1250 default=None, 1251 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 1252 )
!!! 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
UserThreadListResponseDataItemParentMessageActorsItemProfilePicture(pydantic.main.BaseModel):
1255class UserThreadListResponseDataItemParentMessageActorsItemProfilePicture(BaseModel): 1256 file: str | None = Field( 1257 default=None, 1258 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1259 ) 1260 height: int | None = Field( 1261 default=None, description="Height of the image in pixels. `null` if not known." 1262 ) 1263 media: str | None = Field( 1264 default=None, 1265 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1266 ) 1267 mime_type: str | None = Field( 1268 default=None, 1269 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1270 ) 1271 refresh_url: str | None = Field( 1272 default=None, 1273 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.", 1274 ) 1275 url: str | None = Field( 1276 default=None, 1277 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.", 1278 ) 1279 width: int | None = Field( 1280 default=None, description="Width of the image in pixels. `null` if not known." 1281 )
!!! 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
UserThreadListResponseDataItemParentMessageActorsItem(pydantic.main.BaseModel):
1284class UserThreadListResponseDataItemParentMessageActorsItem(BaseModel): 1285 alias: str | None = Field( 1286 default=None, 1287 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 1288 ) 1289 id: str | None = Field( 1290 default=None, 1291 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 1292 ) 1293 name: str | None = Field( 1294 default=None, 1295 description="Display name of the actor shown in the UI. `null` if no name is set.", 1296 ) 1297 profile_picture: UserThreadListResponseDataItemParentMessageActorsItemProfilePicture | None = ( 1298 Field( 1299 default=None, 1300 description="Profile picture for the actor. `null` if the actor has no profile picture.", 1301 ) 1302 )
!!! 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
UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource(pydantic.main.BaseModel):
1305class UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource(BaseModel): 1306 file: str | None = Field( 1307 default=None, 1308 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1309 ) 1310 height: int | None = Field( 1311 default=None, description="Height of the image in pixels. `null` if not known." 1312 ) 1313 media: str | None = Field( 1314 default=None, 1315 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1316 ) 1317 mime_type: str | None = Field( 1318 default=None, 1319 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1320 ) 1321 refresh_url: str | None = Field( 1322 default=None, 1323 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.", 1324 ) 1325 url: str | None = Field( 1326 default=None, 1327 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.", 1328 ) 1329 width: int | None = Field( 1330 default=None, description="Width of the image in pixels. `null` if not known." 1331 )
!!! 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
UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(pydantic.main.BaseModel):
1334class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource(BaseModel): 1335 file: str | None = Field( 1336 default=None, 1337 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1338 ) 1339 height: int | None = Field( 1340 default=None, description="Height of the image in pixels. `null` if not known." 1341 ) 1342 media: str | None = Field( 1343 default=None, 1344 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1345 ) 1346 mime_type: str | None = Field( 1347 default=None, 1348 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1349 ) 1350 refresh_url: str | None = Field( 1351 default=None, 1352 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.", 1353 ) 1354 url: str | None = Field( 1355 default=None, 1356 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.", 1357 ) 1358 width: int | None = Field( 1359 default=None, description="Width of the image in pixels. `null` if not known." 1360 )
!!! 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
UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(pydantic.main.BaseModel):
1363class UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem(BaseModel): 1364 content_type: str | None = Field( 1365 default=None, 1366 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 1367 ) 1368 created_at: datetime | None = Field( 1369 default=None, description="When this variant was created (ISO 8601)." 1370 ) 1371 file: str | None = Field( 1372 default=None, 1373 description="ID of the underlying storage file that backs this variant (`fil_...`).", 1374 ) 1375 filename: str | None = Field( 1376 default=None, 1377 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 1378 ) 1379 height: int | None = Field( 1380 default=None, description="Height of this variant in pixels. `null` if not recorded." 1381 ) 1382 id: str = Field(..., description="Media variant ID (`mvr_...`).") 1383 image_source: ( 1384 UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | None 1385 ) = Field( 1386 default=None, 1387 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 1388 ) 1389 updated_at: datetime | None = Field( 1390 default=None, description="When this variant was last updated (ISO 8601)." 1391 ) 1392 url: str | None = Field( 1393 default=None, 1394 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 1395 ) 1396 variant_key: str | None = Field( 1397 default=None, 1398 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 1399 ) 1400 width: int | None = Field( 1401 default=None, description="Width of this variant in pixels. `null` if not recorded." 1402 )
!!! 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: UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItemImageSource | 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
UserThreadListResponseDataItemParentMessageAttachmentsItem(pydantic.main.BaseModel):
1405class UserThreadListResponseDataItemParentMessageAttachmentsItem(BaseModel): 1406 content_type: str | None = Field( 1407 default=None, 1408 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1409 ) 1410 description: str | None = Field( 1411 default=None, 1412 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.", 1413 ) 1414 filename: str | None = Field( 1415 default=None, 1416 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 1417 ) 1418 height: int | None = Field( 1419 default=None, 1420 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 1421 ) 1422 id: str = Field(..., description="Unique identifier for this attachment within the message.") 1423 image_height: int | None = Field( 1424 default=None, 1425 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1426 ) 1427 image_source: UserThreadListResponseDataItemParentMessageAttachmentsItemImageSource | None = ( 1428 Field( 1429 default=None, 1430 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 1431 ) 1432 ) 1433 image_url: str | None = Field( 1434 default=None, 1435 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 1436 ) 1437 image_width: int | None = Field( 1438 default=None, 1439 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 1440 ) 1441 media_type: str | None = Field( 1442 default=None, 1443 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 1444 ) 1445 name: str | None = Field( 1446 default=None, 1447 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 1448 ) 1449 object: dict[str, Any] | None = Field( 1450 default=None, 1451 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`. Omitted on other types.", 1452 ) 1453 title: str | None = Field( 1454 default=None, 1455 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.", 1456 ) 1457 type: str = Field( 1458 ..., 1459 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, or `"chart"`. Determines which additional fields are present.', 1460 ) 1461 url: str | None = Field( 1462 default=None, 1463 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.", 1464 ) 1465 variants: ( 1466 list[UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None 1467 ) = Field( 1468 default=None, 1469 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 1470 ) 1471 version: int | None = Field( 1472 default=None, 1473 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 1474 ) 1475 width: int | None = Field( 1476 default=None, 1477 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 1478 )
!!! 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.
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. 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", or "chart". 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.
variants: list[UserThreadListResponseDataItemParentMessageAttachmentsItemVariantsItem] | None =
None
Array of available encoding variants for the media item (e.g. different resolutions). Present on media type only; omitted otherwise.
class
UserThreadListResponseDataItemParentMessageReactionsItem(pydantic.main.BaseModel):
1481class UserThreadListResponseDataItemParentMessageReactionsItem(BaseModel): 1482 payload: dict[str, Any] | None = Field( 1483 default=None, 1484 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 1485 ) 1486 type: str = Field( 1487 ..., 1488 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 1489 ) 1490 user: str | None = Field( 1491 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 1492 )
!!! 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
UserThreadListResponseDataItemParentMessage(pydantic.main.BaseModel):
1495class UserThreadListResponseDataItemParentMessage(BaseModel): 1496 acl: UserThreadListResponseDataItemParentMessageAcl | None = Field( 1497 default=None, 1498 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.", 1499 ) 1500 actors: list[UserThreadListResponseDataItemParentMessageActorsItem] | None = Field( 1501 default=None, 1502 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 1503 ) 1504 agent: str | None = Field( 1505 default=None, 1506 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 1507 ) 1508 agent_mode: Literal["cli", "embedded"] | None = Field( 1509 default=None, 1510 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.", 1511 ) 1512 attachments: list[UserThreadListResponseDataItemParentMessageAttachmentsItem] | None = Field( 1513 default=None, 1514 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 1515 ) 1516 branched_thread: str | None = Field( 1517 default=None, 1518 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 1519 ) 1520 content: str | None = Field( 1521 default=None, 1522 description="Text content of the message. `null` for messages that contain only attachments.", 1523 ) 1524 created_at: str | None = Field( 1525 default=None, description="When the message was posted (ISO 8601)." 1526 ) 1527 has_replies: bool | None = Field( 1528 default=None, 1529 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 1530 ) 1531 id: str = Field(..., description="Message ID (`msg_...`).") 1532 idempotency_key: str | None = Field( 1533 default=None, 1534 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 1535 ) 1536 is_deleted: bool | None = Field( 1537 default=None, 1538 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.", 1539 ) 1540 legacy_agent: str | None = Field( 1541 default=None, 1542 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 1543 ) 1544 metadata: dict[str, Any] | None = Field( 1545 default=None, 1546 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 1547 ) 1548 org: str | None = Field( 1549 default=None, description="ID of the organization that owns this message (`org_...`)." 1550 ) 1551 reactions: list[UserThreadListResponseDataItemParentMessageReactionsItem] | None = Field( 1552 default=None, 1553 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.", 1554 ) 1555 rendering_mode: str | None = Field( 1556 default=None, 1557 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.', 1558 ) 1559 replies: list[dict[str, Any]] | None = Field( 1560 default=None, 1561 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 1562 ) 1563 replies_after_cursor: str | None = Field( 1564 default=None, 1565 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 1566 ) 1567 replies_before_cursor: str | None = Field( 1568 default=None, 1569 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 1570 ) 1571 reply_count: int | None = Field( 1572 default=None, 1573 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 1574 ) 1575 reply_to: dict[str, Any] | None = Field( 1576 default=None, 1577 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.", 1578 ) 1579 root_message_id: str | None = Field( 1580 default=None, 1581 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.", 1582 ) 1583 sandbox: str | None = Field( 1584 default=None, 1585 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 1586 ) 1587 team: str | None = Field( 1588 default=None, 1589 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 1590 ) 1591 thread: str | None = Field( 1592 default=None, description="ID of the thread this message belongs to (`thr_...`)." 1593 ) 1594 type: str | None = Field( 1595 default=None, 1596 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.", 1597 ) 1598 user: str | dict[str, Any] | None = Field( 1599 default=None, 1600 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.", 1601 ) 1602 visibility: Literal["default", "private"] | None = Field( 1603 default=None, 1604 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.", 1605 )
!!! 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
UserThreadListResponseDataItemParticipantsItem(pydantic.main.BaseModel):
1608class UserThreadListResponseDataItemParticipantsItem(BaseModel): 1609 alias: str | None = Field( 1610 default=None, description="Short handle or alias for the user. `null` if not set." 1611 ) 1612 app: str | None = Field( 1613 default=None, 1614 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.", 1615 ) 1616 app_name: str | None = Field( 1617 default=None, 1618 description="Display name of the user's app. `null` when the app association was not preloaded by the caller.", 1619 ) 1620 created_by_agent_user: str | None = Field( 1621 default=None, 1622 description="Agent user that created this account (`usr_...`). `null` unless an agent created it.", 1623 ) 1624 created_by_developer: str | None = Field( 1625 default=None, 1626 description="Developer account that created this user (`dva_...`). `null` unless created via a developer token.", 1627 ) 1628 created_by_org: str | None = Field( 1629 default=None, 1630 description="Org of the principal that created this user (`org_...`). `null` on legacy rows.", 1631 ) 1632 created_by_team: str | None = Field( 1633 default=None, 1634 description="Team that created this user (`tem_...`). `null` unless created as a team.", 1635 ) 1636 created_by_user: str | None = Field( 1637 default=None, 1638 description="User who created this account (`usr_...`). `null` on self-signup or legacy rows.", 1639 ) 1640 email: str | None = Field(default=None, description="Email address of the user.") 1641 id: str = Field(..., description="User ID (`usr_...`).") 1642 is_system_user: bool | None = Field( 1643 default=None, 1644 description="`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.", 1645 ) 1646 metadata: dict[str, Any] | None = Field( 1647 default=None, 1648 description="Arbitrary key-value metadata attached to the user. Defaults to an empty object.", 1649 ) 1650 name: str | None = Field( 1651 default=None, 1652 description="Full display name of the user. `null` if the user has not set a name.", 1653 ) 1654 org: str | None = Field( 1655 default=None, 1656 description="ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.", 1657 ) 1658 org_name: str | None = Field( 1659 default=None, 1660 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.", 1661 ) 1662 org_role: str | None = Field( 1663 default=None, 1664 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.', 1665 ) 1666 org_slug: str | None = Field( 1667 default=None, 1668 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.", 1669 ) 1670 sandbox: str | None = Field( 1671 default=None, 1672 description="ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.", 1673 ) 1674 sandbox_name: str | None = Field( 1675 default=None, 1676 description="Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.", 1677 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem(pydantic.main.BaseModel):
1680class UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem(BaseModel): 1681 actions: list[str] = Field( 1682 ..., 1683 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1684 ) 1685 principal: str | None = Field( 1686 default=None, 1687 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"`.', 1688 ) 1689 principal_type: str = Field( 1690 ..., 1691 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1692 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(pydantic.main.BaseModel):
1695class UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem(BaseModel): 1696 actions: list[str] = Field( 1697 ..., 1698 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 1699 ) 1700 principal: str | None = Field( 1701 default=None, 1702 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"`.', 1703 ) 1704 principal_type: str = Field( 1705 ..., 1706 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1707 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(pydantic.main.BaseModel):
1710class UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem(BaseModel): 1711 principal: str | None = Field( 1712 default=None, 1713 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"`.', 1714 ) 1715 principal_type: str = Field( 1716 ..., 1717 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 1718 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemAcl(pydantic.main.BaseModel):
1721class UserThreadListResponseDataItemParticipatingAgentsItemAcl(BaseModel): 1722 add: list[UserThreadListResponseDataItemParticipatingAgentsItemAclAddItem] | None = Field( 1723 default=None, 1724 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 1725 ) 1726 grants: list[UserThreadListResponseDataItemParticipatingAgentsItemAclGrantsItem] | None = Field( 1727 default=None, 1728 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`.", 1729 ) 1730 remove: list[UserThreadListResponseDataItemParticipatingAgentsItemAclRemoveItem] | None = Field( 1731 default=None, 1732 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 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.
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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo(pydantic.main.BaseModel):
1736class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo( 1737 BaseModel 1738): 1739 file: str | None = Field( 1740 default=None, 1741 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1742 ) 1743 height: int | None = Field( 1744 default=None, description="Height of the image in pixels. `null` if not known." 1745 ) 1746 media: str | None = Field( 1747 default=None, 1748 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 1749 ) 1750 mime_type: str | None = Field( 1751 default=None, 1752 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 1753 ) 1754 refresh_url: str | None = Field( 1755 default=None, 1756 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.", 1757 ) 1758 url: str | None = Field( 1759 default=None, 1760 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.", 1761 ) 1762 width: int | None = Field( 1763 default=None, description="Width of the image in pixels. `null` if not known." 1764 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem(pydantic.main.BaseModel):
1767class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 1768 BaseModel 1769): 1770 description: str | None = Field( 1771 default=None, 1772 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 1773 ) 1774 name: str = Field( 1775 ..., 1776 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 1777 ) 1778 required: bool = Field( 1779 ..., 1780 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 1781 ) 1782 type: str = Field( 1783 ..., 1784 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 1785 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills(pydantic.main.BaseModel):
1788class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills( 1789 BaseModel 1790): 1791 participants: dict[str, Any] | None = Field( 1792 default=None, 1793 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 1794 ) 1795 payload: dict[str, Any] | None = Field( 1796 default=None, 1797 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.", 1798 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract(pydantic.main.BaseModel):
1801class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract( 1802 BaseModel 1803): 1804 input_schema: dict[str, Any] | None = Field( 1805 default=None, 1806 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 1807 ) 1808 participants: ( 1809 list[ 1810 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem 1811 ] 1812 | None 1813 ) = Field( 1814 default=None, 1815 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.", 1816 ) 1817 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 1818 ..., 1819 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 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.
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[UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractParticipantsItem] | 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContractPrefills =
PydanticUndefined
Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.
class
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails(pydantic.main.BaseModel):
1823class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails( 1824 BaseModel 1825): 1826 automation_type: str | None = Field( 1827 default=None, 1828 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 1829 ) 1830 invoke_contract: ( 1831 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract 1832 | None 1833 ) = Field( 1834 default=None, 1835 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.", 1836 ) 1837 type: Literal["automation"] = Field( 1838 default="automation", 1839 description="Template-details discriminator. Always `automation` for this variant.", 1840 )
!!! 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetailsInvokeContract | 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem(pydantic.main.BaseModel):
1843class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem( 1844 BaseModel 1845): 1846 description: str | None = Field( 1847 default=None, 1848 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.", 1849 ) 1850 details: ( 1851 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails 1852 | None 1853 ) = Field( 1854 default=None, 1855 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 1856 ) 1857 display_name: str | None = Field( 1858 default=None, 1859 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`.", 1860 ) 1861 id: str | None = Field( 1862 default=None, 1863 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 1864 ) 1865 kind: str = Field( 1866 ..., 1867 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 1868 ) 1869 lookup_key: str | None = Field( 1870 default=None, 1871 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 1872 ) 1873 name: str | None = Field( 1874 default=None, 1875 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`.", 1876 ) 1877 readme_url: str | None = Field( 1878 default=None, 1879 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`.", 1880 ) 1881 virtual_path: str | None = Field( 1882 default=None, 1883 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 1884 )
!!! 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItemDetails | 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(pydantic.main.BaseModel):
1887class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution(BaseModel): 1888 category_keys: list[str] | None = Field( 1889 default=None, 1890 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 1891 ) 1892 created_at: str | None = Field( 1893 default=None, description="When the Solution config was first imported (ISO 8601)." 1894 ) 1895 description: str | None = Field( 1896 default=None, 1897 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.", 1898 ) 1899 events: dict[str, Any] | None = Field( 1900 default=None, 1901 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.", 1902 ) 1903 id: str = Field(..., description="Solution config ID (`cfg_...`).") 1904 image_url: str | None = Field( 1905 default=None, 1906 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, and always `null` for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.", 1907 ) 1908 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 1909 latest_solution: str | None = Field( 1910 default=None, 1911 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 1912 ) 1913 latest_version: str | None = Field( 1914 default=None, 1915 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 1916 ) 1917 lookup_key: str | None = Field( 1918 default=None, 1919 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 1920 ) 1921 metadata: dict[str, Any] | None = Field( 1922 default=None, 1923 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.", 1924 ) 1925 name: str | None = Field( 1926 default=None, 1927 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 1928 ) 1929 org: str | None = Field( 1930 default=None, 1931 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.", 1932 ) 1933 org_logo: ( 1934 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo 1935 | None 1936 ) = Field( 1937 default=None, 1938 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.", 1939 ) 1940 org_name: str | None = Field( 1941 default=None, 1942 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 1943 ) 1944 org_slug: str | None = Field( 1945 default=None, 1946 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.", 1947 ) 1948 owners: list[str] = Field( 1949 ..., 1950 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 1951 ) 1952 readme_url: str | None = Field( 1953 default=None, 1954 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`.", 1955 ) 1956 screenshot_urls: list[str] | None = Field( 1957 default=None, 1958 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.", 1959 ) 1960 solution_id: str | None = Field( 1961 default=None, 1962 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.", 1963 ) 1964 solution_version: str | None = Field( 1965 default=None, 1966 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 1967 ) 1968 tag_keys: list[str] | None = Field( 1969 default=None, 1970 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 1971 ) 1972 template_kind: str | None = Field( 1973 default=None, 1974 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 1975 ) 1976 templates: list[ 1977 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem 1978 ] = Field( 1979 ..., 1980 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.", 1981 ) 1982 updated_at: str | None = Field( 1983 default=None, description="When the Solution config was last modified (ISO 8601)." 1984 ) 1985 upgrade_available: bool = Field( 1986 ..., 1987 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.", 1988 ) 1989 virtual_path: str | None = Field( 1990 default=None, 1991 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.", 1992 )
!!! 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, and always null for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.
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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionOrgLogo | 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[UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolutionTemplatesItem] =
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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(pydantic.main.BaseModel):
1995class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo(BaseModel): 1996 file: str | None = Field( 1997 default=None, 1998 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 1999 ) 2000 height: int | None = Field( 2001 default=None, description="Height of the image in pixels. `null` if not known." 2002 ) 2003 media: str | None = Field( 2004 default=None, 2005 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2006 ) 2007 mime_type: str | None = Field( 2008 default=None, 2009 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2010 ) 2011 refresh_url: str | None = Field( 2012 default=None, 2013 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.", 2014 ) 2015 url: str | None = Field( 2016 default=None, 2017 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.", 2018 ) 2019 width: int | None = Field( 2020 default=None, description="Width of the image in pixels. `null` if not known." 2021 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem(pydantic.main.BaseModel):
2024class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem( 2025 BaseModel 2026): 2027 description: str | None = Field( 2028 default=None, 2029 description="Workflow-authored explanation of the slot's role. `null` when the workflow declares none.", 2030 ) 2031 name: str = Field( 2032 ..., 2033 description="The slot's name, as referenced by the workflow. Supply the chosen agent under the top-level `participants[name]` field when invoking.", 2034 ) 2035 required: bool = Field( 2036 ..., 2037 description="Whether the workflow requires this slot to be filled for the run to complete its embedded stages.", 2038 ) 2039 type: str = Field( 2040 ..., 2041 description='The kind of principal the slot accepts. Currently always `"agent_user"` the value supplied at invoke is an agent ID (`agi_...`).', 2042 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills(pydantic.main.BaseModel):
2045class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills( 2046 BaseModel 2047): 2048 participants: dict[str, Any] | None = Field( 2049 default=None, 2050 description="Participant slot-to-agent mappings applied by the platform. Caller values at these slots must match exactly.", 2051 ) 2052 payload: dict[str, Any] | None = Field( 2053 default=None, 2054 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.", 2055 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract(pydantic.main.BaseModel):
2058class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract( 2059 BaseModel 2060): 2061 input_schema: dict[str, Any] | None = Field( 2062 default=None, 2063 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2064 ) 2065 participants: ( 2066 list[ 2067 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem 2068 ] 2069 | None 2070 ) = Field( 2071 default=None, 2072 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.", 2073 ) 2074 prefills: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills = Field( 2075 ..., 2076 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2077 )
!!! 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[UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractParticipantsItem] | 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContractPrefills =
PydanticUndefined
Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.
class
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails(pydantic.main.BaseModel):
2080class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails( 2081 BaseModel 2082): 2083 automation_type: str | None = Field( 2084 default=None, 2085 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2086 ) 2087 invoke_contract: ( 2088 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract 2089 | None 2090 ) = Field( 2091 default=None, 2092 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.", 2093 ) 2094 type: Literal["automation"] = Field( 2095 default="automation", 2096 description="Template-details discriminator. Always `automation` for this variant.", 2097 )
!!! 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetailsInvokeContract | 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem(pydantic.main.BaseModel):
2100class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem( 2101 BaseModel 2102): 2103 description: str | None = Field( 2104 default=None, 2105 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.", 2106 ) 2107 details: ( 2108 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails 2109 | None 2110 ) = Field( 2111 default=None, 2112 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2113 ) 2114 display_name: str | None = Field( 2115 default=None, 2116 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`.", 2117 ) 2118 id: str | None = Field( 2119 default=None, 2120 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2121 ) 2122 kind: str = Field( 2123 ..., 2124 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2125 ) 2126 lookup_key: str | None = Field( 2127 default=None, 2128 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2129 ) 2130 name: str | None = Field( 2131 default=None, 2132 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`.", 2133 ) 2134 readme_url: str | None = Field( 2135 default=None, 2136 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`.", 2137 ) 2138 virtual_path: str | None = Field( 2139 default=None, 2140 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2141 )
!!! 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItemDetails | 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(pydantic.main.BaseModel):
2144class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution(BaseModel): 2145 category_keys: list[str] | None = Field( 2146 default=None, 2147 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2148 ) 2149 created_at: str | None = Field( 2150 default=None, description="When the Solution config was first imported (ISO 8601)." 2151 ) 2152 description: str | None = Field( 2153 default=None, 2154 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.", 2155 ) 2156 events: dict[str, Any] | None = Field( 2157 default=None, 2158 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.", 2159 ) 2160 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2161 image_url: str | None = Field( 2162 default=None, 2163 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, and always `null` for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.", 2164 ) 2165 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2166 latest_solution: str | None = Field( 2167 default=None, 2168 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2169 ) 2170 latest_version: str | None = Field( 2171 default=None, 2172 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2173 ) 2174 lookup_key: str | None = Field( 2175 default=None, 2176 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2177 ) 2178 metadata: dict[str, Any] | None = Field( 2179 default=None, 2180 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.", 2181 ) 2182 name: str | None = Field( 2183 default=None, 2184 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2185 ) 2186 org: str | None = Field( 2187 default=None, 2188 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.", 2189 ) 2190 org_logo: ( 2191 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | None 2192 ) = Field( 2193 default=None, 2194 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.", 2195 ) 2196 org_name: str | None = Field( 2197 default=None, 2198 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2199 ) 2200 org_slug: str | None = Field( 2201 default=None, 2202 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.", 2203 ) 2204 owners: list[str] = Field( 2205 ..., 2206 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2207 ) 2208 readme_url: str | None = Field( 2209 default=None, 2210 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`.", 2211 ) 2212 screenshot_urls: list[str] | None = Field( 2213 default=None, 2214 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.", 2215 ) 2216 solution_id: str | None = Field( 2217 default=None, 2218 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.", 2219 ) 2220 solution_version: str | None = Field( 2221 default=None, 2222 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2223 ) 2224 tag_keys: list[str] | None = Field( 2225 default=None, 2226 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2227 ) 2228 template_kind: str | None = Field( 2229 default=None, 2230 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2231 ) 2232 templates: list[ 2233 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem 2234 ] = Field( 2235 ..., 2236 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.", 2237 ) 2238 updated_at: str | None = Field( 2239 default=None, description="When the Solution config was last modified (ISO 8601)." 2240 ) 2241 upgrade_available: bool = Field( 2242 ..., 2243 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.", 2244 ) 2245 virtual_path: str | None = Field( 2246 default=None, 2247 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.", 2248 )
!!! 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, and always null for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.
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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionOrgLogo | 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[UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolutionTemplatesItem] =
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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(pydantic.main.BaseModel):
2251class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate(BaseModel): 2252 created_at: datetime | None = Field( 2253 default=None, description="When this template config was created (ISO 8601)." 2254 ) 2255 description: str | None = Field( 2256 default=None, 2257 description="Description of the template from the config body. `null` if the current version has no `description` field.", 2258 ) 2259 display_name: str | None = Field( 2260 default=None, 2261 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 2262 ) 2263 id: str = Field(..., description="Template config ID (`cfg_...`).") 2264 kind: str = Field( 2265 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 2266 ) 2267 lookup_key: str | None = Field( 2268 default=None, 2269 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 2270 ) 2271 name: str | None = Field( 2272 default=None, 2273 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 2274 ) 2275 updated_at: datetime | None = Field( 2276 default=None, description="When this template config was last modified (ISO 8601)." 2277 ) 2278 virtual_path: str | None = Field( 2279 default=None, 2280 description="Virtual filesystem path for this template config. `null` if not set.", 2281 )
!!! 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
UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution(pydantic.main.BaseModel):
2284class UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution(BaseModel): 2285 current_solution: ( 2286 UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | None 2287 ) = Field( 2288 default=None, 2289 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.", 2290 ) 2291 solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution = Field( 2292 ..., 2293 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.", 2294 ) 2295 template: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate = Field( 2296 ..., 2297 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2298 )
!!! 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionCurrentSolution | 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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionSolution =
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: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolutionTemplate =
PydanticUndefined
Summary of the AgentTemplate config (cfg_...) the agent was last provisioned or updated from.
class
UserThreadListResponseDataItemParticipatingAgentsItem(pydantic.main.BaseModel):
2301class UserThreadListResponseDataItemParticipatingAgentsItem(BaseModel): 2302 acl: UserThreadListResponseDataItemParticipatingAgentsItemAcl | None = Field( 2303 default=None, 2304 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.", 2305 ) 2306 app: str | None = Field( 2307 default=None, description="ID of the application that owns this agent (`dap_...`)." 2308 ) 2309 created_at: str | None = Field( 2310 default=None, description="When the agent was created (ISO 8601)." 2311 ) 2312 default_model: str | None = Field( 2313 default=None, 2314 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2315 ) 2316 description: str | None = Field( 2317 default=None, 2318 description="Human-readable description of what the agent does. `null` if not set.", 2319 ) 2320 email: str | None = Field( 2321 default=None, 2322 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2323 ) 2324 id: str = Field(..., description="Agent ID (`agi_...`).") 2325 identity: str | None = Field( 2326 default=None, 2327 description="System-level identity prompt that shapes the agent's persona and behavior.", 2328 ) 2329 last_applied_template_config: str | None = Field( 2330 default=None, 2331 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2332 ) 2333 lookup_key: str | None = Field( 2334 default=None, 2335 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2336 ) 2337 metadata: dict[str, Any] | None = Field( 2338 default=None, 2339 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2340 ) 2341 name: str | None = Field( 2342 default=None, description="Human-readable display name for the agent. `null` if not set." 2343 ) 2344 org: str | None = Field( 2345 default=None, 2346 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2347 ) 2348 org_name: str | None = Field( 2349 default=None, 2350 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.", 2351 ) 2352 originator: str | None = Field( 2353 default=None, 2354 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2355 ) 2356 phone_number: str | None = Field( 2357 default=None, 2358 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2359 ) 2360 sandbox: str | None = Field( 2361 default=None, 2362 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2363 ) 2364 source_solution: UserThreadListResponseDataItemParticipatingAgentsItemSourceSolution | None = ( 2365 Field( 2366 default=None, 2367 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.", 2368 ) 2369 ) 2370 team: str | None = Field( 2371 default=None, 2372 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2373 ) 2374 template_upgrade_available: bool | None = Field( 2375 default=None, 2376 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`).", 2377 ) 2378 updated_at: str | None = Field( 2379 default=None, description="When the agent was last modified (ISO 8601)." 2380 ) 2381 user: str | None = Field( 2382 default=None, 2383 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 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.
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
UserThreadListResponseDataItemSettings(pydantic.main.BaseModel):
2387class UserThreadListResponseDataItemSettings(BaseModel): 2388 agent_enabled: bool | None = Field( 2389 default=None, 2390 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.", 2391 )
!!! 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
UserThreadListResponseDataItem(pydantic.main.BaseModel):
2394class UserThreadListResponseDataItem(BaseModel): 2395 agent_user: str | None = Field( 2396 default=None, 2397 description="ID of the agent that owns this thread (`agt_...`). `null` for user-owned or team-owned threads.", 2398 ) 2399 created_at: str | None = Field( 2400 default=None, description="When the thread was created (ISO 8601)." 2401 ) 2402 creator: str | dict[str, Any] | None = Field( 2403 default=None, 2404 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.", 2405 ) 2406 description: str | None = Field( 2407 default=None, 2408 description="Optional description or purpose statement for the thread. `null` if not set.", 2409 ) 2410 id: str = Field(..., description="Thread ID (`thr_...`).") 2411 is_channel: bool | None = Field( 2412 default=None, 2413 description="Whether this thread operates as a channel a multi-member broadcast-style conversation.", 2414 ) 2415 is_default: bool | None = Field( 2416 default=None, 2417 description="Whether this is the default thread for its owner. Each user or team has at most one default thread.", 2418 ) 2419 is_transient: bool | None = Field( 2420 default=None, 2421 description="Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.", 2422 ) 2423 is_unlisted: bool | None = Field( 2424 default=None, 2425 description="Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.", 2426 ) 2427 key: str | None = Field( 2428 default=None, 2429 description="Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. `null` if not set.", 2430 ) 2431 kind: str | None = Field( 2432 default=None, 2433 description='Thread subtype: `"standard"` for ordinary threads, `"personal"` for a user-and-owned-agents roster, `"slack_mirror"` for the membership-strict mirror of a Slack channel, or `"slashwork_mirror"` for the membership-strict mirror of a Slashwork group. `personal` is an explicit user-thread creation option; mirror kinds are server-derived.', 2434 ) 2435 last_activity: str | None = Field( 2436 default=None, 2437 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.", 2438 ) 2439 last_message_preview: str | None = Field( 2440 default=None, 2441 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.", 2442 ) 2443 last_message_sender: str | None = Field( 2444 default=None, 2445 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.", 2446 ) 2447 metadata: dict[str, Any] | None = Field( 2448 default=None, 2449 description="Arbitrary key-value metadata attached to the thread. Shape is application-defined; `null` if no metadata has been set.", 2450 ) 2451 muted: bool | None = Field( 2452 default=None, 2453 description="Whether the authenticated user has muted notifications for this thread. `true` suppresses all notification delivery.", 2454 ) 2455 org: str | None = Field( 2456 default=None, 2457 description="ID of the organization this thread belongs to (`org_...`). `null` for threads outside an org context.", 2458 ) 2459 parent_message: UserThreadListResponseDataItemParentMessage | None = Field( 2460 default=None, 2461 description="The message that spawned this thread as a sub-thread. `null` for top-level threads.", 2462 ) 2463 participant: list[str] | None = Field( 2464 default=None, 2465 description="Array of participant user IDs (`usr_...`) who are members of this thread.", 2466 ) 2467 participants: list[UserThreadListResponseDataItemParticipantsItem] | None = Field( 2468 default=None, 2469 description="Expanded participant user objects for each member of this thread. Populated only when the association is loaded.", 2470 ) 2471 participating_actor: list[str] | None = Field( 2472 default=None, 2473 description="Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.", 2474 ) 2475 participating_agents: list[UserThreadListResponseDataItemParticipatingAgentsItem] | None = ( 2476 Field( 2477 default=None, 2478 description="Expanded agent objects for all agents participating in this thread. Present only when agent enrichment is requested.", 2479 ) 2480 ) 2481 role: str | None = Field( 2482 default=None, 2483 description='The authenticated user\'s membership role in this thread, e.g. `"owner"`, `"member"`, or `"viewer"`. `null` if the user is not a member.', 2484 ) 2485 sandbox: str | None = Field( 2486 default=None, 2487 description="ID of the developer sandbox this thread is scoped to (`dsb_...`). `null` for production threads.", 2488 ) 2489 settings: UserThreadListResponseDataItemSettings | None = Field( 2490 default=None, 2491 description="Per-thread configuration settings controlling AI agent behavior for this thread.", 2492 ) 2493 slug: str | None = Field( 2494 default=None, 2495 description="URL-safe slug for the thread, used in human-readable permalinks. `null` if not assigned.", 2496 ) 2497 sub_threads: list[dict[str, Any]] | None = Field( 2498 default=None, 2499 description="Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.", 2500 ) 2501 tags: list[str] | None = Field( 2502 default=None, 2503 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.', 2504 ) 2505 team: str | None = Field( 2506 default=None, 2507 description="ID of the team that owns this thread (`team_...`). `null` for user-owned or agent-owned threads.", 2508 ) 2509 title: str | None = Field( 2510 default=None, 2511 description="Human-readable name of the thread. `null` if no title has been set.", 2512 ) 2513 ttl: str | None = Field( 2514 default=None, 2515 description="Offset-free expiry timestamp after which the thread may be automatically cleaned up. `null` if the thread does not expire.", 2516 ) 2517 unread_count: int | None = Field( 2518 default=None, 2519 description="Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.", 2520 ) 2521 updated_at: str | None = Field( 2522 default=None, description="When the thread was last modified (ISO 8601)." 2523 ) 2524 user: str | None = Field( 2525 default=None, 2526 description="ID of the user who owns this thread (`usr_...`). `null` for team-owned or agent-owned threads.", 2527 ) 2528 visibility: Literal["team", "restricted", "private"] = Field( 2529 ..., 2530 description="Who can read the thread: `team` for every owning-team member, `restricted` for team-readable threads with an explicit roster, or `private` for roster-only access.", 2531 )
!!! 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, "slack_mirror" for the membership-strict mirror of a Slack channel, or "slashwork_mirror" for the membership-strict mirror of a Slashwork group. personal is an explicit user-thread creation option; 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.
user: str | None =
None
ID of the user who owns this thread (usr_...). null for team-owned or agent-owned threads.
visibility: Literal['team', 'restricted', 'private'] =
PydanticUndefined
Who can read the thread: team for every owning-team member, restricted for team-readable threads with an explicit roster, or private for roster-only access.
class
UserThreadListResponse(pydantic.main.BaseModel):
2534class UserThreadListResponse(BaseModel): 2535 """ 2536 Successful response 2537 """ 2538 2539 data: list[UserThreadListResponseDataItem] = Field( 2540 ..., 2541 description="Array of thread objects matching the requested filters and agent narrowings.", 2542 )
Successful response
class
TokenListResponseDataItem(pydantic.main.BaseModel):
2545class TokenListResponseDataItem(BaseModel): 2546 created_at: datetime | None = Field( 2547 default=None, description="When this token was created (ISO 8601)." 2548 ) 2549 created_by_agent_user: str | None = Field( 2550 default=None, 2551 description="Agent user that minted this token (`usr_...`). `null` unless an agent minted it.", 2552 ) 2553 created_by_developer: str | None = Field( 2554 default=None, 2555 description="Developer account that minted this token (`dva_...`). `null` unless minted with a developer token.", 2556 ) 2557 created_by_org: str | None = Field( 2558 default=None, 2559 description="Org of the principal that minted this token (`org_...`). `null` on legacy rows.", 2560 ) 2561 created_by_team: str | None = Field( 2562 default=None, 2563 description="Team that minted this token (`tem_...`). `null` unless minted as a team.", 2564 ) 2565 created_by_user: str | None = Field( 2566 default=None, 2567 description="User who minted this token (`usr_...`). Distinct from the token subject. `null` on legacy rows.", 2568 ) 2569 expires_at: datetime | None = Field( 2570 default=None, 2571 description="When the token expires. `null` on legacy rows that predate stored expiry.", 2572 ) 2573 id: str = Field(..., description="Token ID (`sat_...`).") 2574 last_used_at: datetime | None = Field( 2575 default=None, 2576 description="When this token was last used to authenticate a request. `null` if the token has never been used.", 2577 ) 2578 name: str | None = Field( 2579 default=None, 2580 description="Human-readable label assigned to this token at creation time. `null` when no label was supplied.", 2581 ) 2582 revoked_at: datetime | None = Field( 2583 default=None, 2584 description="When this token was revoked. `null` if the token is still active.", 2585 ) 2586 scopes: str | None = Field( 2587 default=None, 2588 description="Space-separated OAuth scopes stamped on the token. `null` on legacy rows; treat as `full_access`.", 2589 ) 2590 token: str | None = Field( 2591 default=None, 2592 description="Raw bearer token string. Present only in the response to the create request; never returned again after that.", 2593 )
!!! 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.
created_by_agent_user: str | None =
None
Agent user that minted this token (usr_...). null unless an agent minted it.
created_by_developer: str | None =
None
Developer account that minted this token (dva_...). null unless minted with a developer token.
created_by_org: str | None =
None
Org of the principal that minted this token (org_...). null on legacy rows.
created_by_team: str | None =
None
Team that minted this token (tem_...). null unless minted as a team.
created_by_user: str | None =
None
User who minted this token (usr_...). Distinct from the token subject. null on legacy rows.
expires_at: datetime.datetime | None =
None
When the token expires. null on legacy rows that predate stored expiry.
last_used_at: datetime.datetime | None =
None
When this token was last used to authenticate a request. null if the token has never been used.
name: str | None =
None
Human-readable label assigned to this token at creation time. null when no label was supplied.
revoked_at: datetime.datetime | None =
None
When this token was revoked. null if the token is still active.
class
TokenListResponse(pydantic.main.BaseModel):
2596class TokenListResponse(BaseModel): 2597 """ 2598 Successful response 2599 """ 2600 2601 data: list[TokenListResponseDataItem] = Field( 2602 ..., description="Array of access token objects. Raw JWT values are not included." 2603 )
Successful response
class
UserArtifactsResponseDataItemImageSource(pydantic.main.BaseModel):
2606class UserArtifactsResponseDataItemImageSource(BaseModel): 2607 file: str | None = Field( 2608 default=None, 2609 description="ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.", 2610 ) 2611 height: int | None = Field( 2612 default=None, description="Height of the image in pixels. `null` if not known." 2613 ) 2614 media: str | None = Field( 2615 default=None, 2616 description="ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.", 2617 ) 2618 mime_type: str | None = Field( 2619 default=None, 2620 description='MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.', 2621 ) 2622 refresh_url: str | None = Field( 2623 default=None, 2624 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.", 2625 ) 2626 url: str | None = Field( 2627 default=None, 2628 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.", 2629 ) 2630 width: int | None = Field( 2631 default=None, description="Width of the image in pixels. `null` if not known." 2632 )
!!! 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
UserArtifactsResponseDataItem(pydantic.main.BaseModel):
2635class UserArtifactsResponseDataItem(BaseModel): 2636 agent: str | None = Field( 2637 default=None, 2638 description="ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.", 2639 ) 2640 content_type: str | None = Field( 2641 default=None, 2642 description='MIME type of the current version\'s file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.', 2643 ) 2644 created_at: datetime | None = Field( 2645 default=None, description="When the artifact was first created (ISO 8601)." 2646 ) 2647 current_version: str | None = Field( 2648 default=None, 2649 description="ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.", 2650 ) 2651 description: str | None = Field( 2652 default=None, 2653 description="Optional longer description of the artifact's contents or purpose. `null` if not set.", 2654 ) 2655 file: str | None = Field( 2656 default=None, 2657 description="Storage file ID for the current version (`fil_...`). `null` if no file is attached.", 2658 ) 2659 file_name: str | None = Field( 2660 default=None, 2661 description='Original filename of the current version\'s file, e.g. `"output.csv"`. `null` if no file is attached.', 2662 ) 2663 file_url: str | None = Field( 2664 default=None, 2665 description="Short-lived signed URL for downloading the current version's file. `null` if no file is attached.", 2666 ) 2667 id: str = Field(..., description="Artifact ID (`art_...`).") 2668 image_source: UserArtifactsResponseDataItemImageSource | None = Field( 2669 default=None, 2670 description='Image source metadata for rendering the current version\'s file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.', 2671 ) 2672 name: str | None = Field( 2673 default=None, 2674 description='Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.', 2675 ) 2676 org: str | None = Field( 2677 default=None, description="ID of the organization this artifact belongs to (`org_...`)." 2678 ) 2679 sandbox: str | None = Field( 2680 default=None, 2681 description="Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.", 2682 ) 2683 team: str | None = Field( 2684 default=None, 2685 description="ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.", 2686 ) 2687 thread: str | None = Field( 2688 default=None, 2689 description="ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.", 2690 ) 2691 updated_at: datetime | None = Field( 2692 default=None, description="When the artifact record was last modified (ISO 8601)." 2693 ) 2694 user: str | None = Field( 2695 default=None, 2696 description="ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.", 2697 ) 2698 version: int | None = Field( 2699 default=None, 2700 description="Current version number of the artifact. Increments each time a new version is published.", 2701 )
!!! 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 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.
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.
thread: str | None =
None
ID of the thread in which this artifact was created (thr_...). null if not thread-scoped.
class
UserArtifactsResponse(pydantic.main.BaseModel):
2704class UserArtifactsResponse(BaseModel): 2705 """ 2706 Successful response 2707 """ 2708 2709 data: list[UserArtifactsResponseDataItem] = Field( 2710 ..., description="Array of artifact objects belonging to the user." 2711 )
Successful response
class
UserOrgsResponseDataItem(pydantic.main.BaseModel):
2714class UserOrgsResponseDataItem(BaseModel): 2715 created_at: datetime | None = Field( 2716 default=None, description="When this organization was created (ISO 8601)." 2717 ) 2718 description: str | None = Field( 2719 default=None, 2720 description="Short human-readable description of the organization. `null` if not set.", 2721 ) 2722 domain: str | None = Field( 2723 default=None, 2724 description='Primary domain associated with the organization, e.g. `"acme.com"`. `null` if not configured.', 2725 ) 2726 id: str = Field(..., description="Organization ID (`org_...`).") 2727 industry: str | None = Field( 2728 default=None, 2729 description='Industry category the organization belongs to, e.g. `"fintech"` or `"healthcare"`. `null` if not set.', 2730 ) 2731 name: str | None = Field( 2732 default=None, 2733 description="Display name of the organization. `null` if the org has not set a name.", 2734 ) 2735 onboarding_solution_lookup_key: str | None = Field( 2736 default=None, 2737 description="Lookup key (`sol-...`) of the Solution currently driving this org's customer onboarding the active onboarding solution pointer. Stamped when the org is linked into a vendor's network via an explore-install and re-stamped by every later solution-driven link, so the latest install wins. `null` for vendor-track orgs and invite-driven customers. The onboarding UI reads the referenced Solution's `metadata.onboarding` block to tailor the customer checklist.", 2738 ) 2739 onboarding_track: str | None = Field( 2740 default=None, 2741 description='The new-user experience track this org first completed. `"vendor"` for orgs that onboarded as service providers; `"customer"` for orgs that onboarded as buyers. `null` if onboarding was not tracked.', 2742 ) 2743 owned_products: list[str] | None = Field( 2744 default=None, 2745 description='Catalog product IDs this organization\'s plan includes, e.g. `["agent-rooms"]`, `["agent-solutions"]`, `["agent-customer-management"]`. Empty when the org has no plan. Clients use this to show which products the org actually has rather than inferring from feature flags. Derived from the org\'s plan, so it reflects what is currently paid for.', 2746 ) 2747 sandbox: str | None = Field( 2748 default=None, 2749 description="ID of the sandbox environment scoped to this organization (`snd_...`). `null` for organizations in production mode.", 2750 ) 2751 slug: str | None = Field( 2752 default=None, 2753 description="URL-safe identifier for the organization, used in vanity URLs and slug-based lookups.", 2754 ) 2755 status: str | None = Field( 2756 default=None, 2757 description='Current lifecycle status of the organization, e.g. `"active"` or `"suspended"`. `null` if the status has not been set.', 2758 ) 2759 updated_at: datetime | None = Field( 2760 default=None, description="When this organization was last modified (ISO 8601)." 2761 ) 2762 website: str | None = Field( 2763 default=None, description="Public website URL for the organization. `null` if not set." 2764 )
!!! 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 human-readable description of the organization. null if not set.
domain: str | None =
None
Primary domain associated with the organization, e.g. "acme.com". null if not configured.
industry: str | None =
None
Industry category the organization belongs to, e.g. "fintech" or "healthcare". null if not set.
onboarding_solution_lookup_key: str | None =
None
Lookup key (sol-...) of the Solution currently driving this org's customer onboarding the active onboarding solution pointer. Stamped when the org is linked into a vendor's network via an explore-install and re-stamped by every later solution-driven link, so the latest install wins. null for vendor-track orgs and invite-driven customers. The onboarding UI reads the referenced Solution's metadata.onboarding block to tailor the customer checklist.
onboarding_track: str | None =
None
The new-user experience track this org first completed. "vendor" for orgs that onboarded as service providers; "customer" for orgs that onboarded as buyers. null if onboarding was not tracked.
owned_products: list[str] | None =
None
Catalog product IDs this organization's plan includes, e.g. ["agent-rooms"], ["agent-solutions"], ["agent-customer-management"]. Empty when the org has no plan. Clients use this to show which products the org actually has rather than inferring from feature flags. Derived from the org's plan, so it reflects what is currently paid for.
sandbox: str | None =
None
ID of the sandbox environment scoped to this organization (snd_...). null for organizations in production mode.
slug: str | None =
None
URL-safe identifier for the organization, used in vanity URLs and slug-based lookups.
class
UserOrgsResponse(pydantic.main.BaseModel):
2767class UserOrgsResponse(BaseModel): 2768 """ 2769 Successful response 2770 """ 2771 2772 data: list[UserOrgsResponseDataItem] = Field( 2773 ..., 2774 description="Array of organization objects the user belongs to. Contains at most one item.", 2775 )
Successful response
class
AsyncUserTaskResource:
2778class AsyncUserTaskResource: 2779 def __init__(self, http: HttpClient): 2780 self._http = http 2781 2782 async def list( 2783 self, 2784 user: str, 2785 *, 2786 team: str | None = None, 2787 org: str | None = None, 2788 status: str | None = None, 2789 owner_user: str | None = None, 2790 owner_agent: str | None = None, 2791 priority: int | None = None, 2792 tag: str | None = None, 2793 parent: str | None = None, 2794 source_scope: str | None = None, 2795 source_type: str | None = None, 2796 source_id: str | None = None, 2797 epic: str | None = None, 2798 search: str | None = None, 2799 sort: str | None = None, 2800 order: str | None = None, 2801 due_before: str | None = None, 2802 due_after: str | None = None, 2803 overdue: bool | None = None, 2804 ready: bool | None = None, 2805 limit: int | None = None, 2806 after_cursor: str | None = None, 2807 ) -> UserTaskListResponse: 2808 """ 2809 List an owner's tasks 2810 Returns tasks owned by the specified user or team. You can narrow results using the 2811 optional filters below. By default results are returned in reverse chronological 2812 order (most recently created first); use `sort` and `order` to sort by due date or 2813 priority instead. 2814 User-authenticated callers may list their personal tasks or tasks for teams they 2815 have joined. Privileged callers provide the owner in the route; the owner's 2816 organization is implied by that principal. An explicit `org` is optional and, 2817 when set, must match the owner's organization. 2818 2819 Args: 2820 user: User ID (`usr_...`) for user-scoped tasks. 2821 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 2822 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 2823 status: Filter tasks by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to return tasks in all statuses. 2824 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 2825 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 2826 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 2827 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 2828 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 2829 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 2830 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 2831 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 2832 epic: Return only tasks with this exact epic label. 2833 search: Restrict results to tasks whose name or description contains this string. 2834 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. 2835 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 2836 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. 2837 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 2838 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. 2839 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. 2840 limit: Maximum number of tasks to return. Capped at 100. 2841 after_cursor: Opaque cursor returned by the previous page. 2842 2843 Returns: 2844 Successful response 2845 """ 2846 query: dict[str, object] = {} 2847 if team is not None: 2848 query["team"] = team 2849 if org is not None: 2850 query["org"] = org 2851 if status is not None: 2852 query["status"] = status 2853 if owner_user is not None: 2854 query["owner_user"] = owner_user 2855 if owner_agent is not None: 2856 query["owner_agent"] = owner_agent 2857 if priority is not None: 2858 query["priority"] = priority 2859 if tag is not None: 2860 query["tag"] = tag 2861 if parent is not None: 2862 query["parent"] = parent 2863 if source_scope is not None: 2864 query["source_scope"] = source_scope 2865 if source_type is not None: 2866 query["source_type"] = source_type 2867 if source_id is not None: 2868 query["source_id"] = source_id 2869 if epic is not None: 2870 query["epic"] = epic 2871 if search is not None: 2872 query["search"] = search 2873 if sort is not None: 2874 query["sort"] = sort 2875 if order is not None: 2876 query["order"] = order 2877 if due_before is not None: 2878 query["due_before"] = due_before 2879 if due_after is not None: 2880 query["due_after"] = due_after 2881 if overdue is not None: 2882 query["overdue"] = overdue 2883 if ready is not None: 2884 query["ready"] = ready 2885 if limit is not None: 2886 query["limit"] = limit 2887 if after_cursor is not None: 2888 query["after_cursor"] = after_cursor 2889 return await self._http.request( 2890 f"/api/v1/users/{user}/tasks", 2891 query=query, 2892 response_type=UserTaskListResponse, 2893 ) 2894 2895 async def create(self, user: str, input: UserTaskCreateInput) -> Task: 2896 """ 2897 Create a task for an owner 2898 Creates a new task owned by the specified user or team and returns the full 2899 task object. User-authenticated calls are attributed to the authenticated 2900 user or agent. App-scoped developer and server-to-server callers must provide 2901 the task's explicit `org` scope and an explicit `user` or `agent` actor for 2902 team tasks; a user-owned task reuses the user in the route unless an explicit 2903 agent is supplied. Every referenced principal is validated against the app, 2904 owner, and team membership before creation. 2905 2906 Args: 2907 user: User ID (`usr_...`) for user-scoped tasks. 2908 input: Request body. 2909 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 task owner. 2910 input.org: Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. 2911 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 2912 input.team: Team ID (`tem_...`). The task will be owned by this team. 2913 2914 Returns: 2915 The newly created task. 2916 """ 2917 return await self._http.request( 2918 f"/api/v1/users/{user}/tasks", 2919 method="POST", 2920 body=input, 2921 response_type=Task, 2922 ) 2923 2924 async def blocker_cycles( 2925 self, 2926 user: str, 2927 *, 2928 team: str | None = None, 2929 org: str | None = None, 2930 limit: int | None = None, 2931 after_cursor: str | None = None, 2932 ) -> UserTaskBlockerCyclesResponse: 2933 """ 2934 List task blocker cycles 2935 Runs an on-demand diagnostic over unfinished tasks owned by the specified 2936 team or user and returns a forward cursor-paginated page of complete cyclic 2937 blocker components. Detection is bounded to owners with at most 100 2938 unfinished tasks. This endpoint is read-only: cycles do not prevent task 2939 updates, lease acquisition, or completion. 2940 2941 Args: 2942 user: User ID (`usr_...`) for user-scoped tasks. 2943 team: Team ID (`tem_...`) owning the tasks. 2944 org: Optional organization context for privileged callers. 2945 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 2946 after_cursor: Opaque cursor returned by the preceding page. 2947 2948 Returns: 2949 Successful response 2950 """ 2951 query: dict[str, object] = {} 2952 if team is not None: 2953 query["team"] = team 2954 if org is not None: 2955 query["org"] = org 2956 if limit is not None: 2957 query["limit"] = limit 2958 if after_cursor is not None: 2959 query["after_cursor"] = after_cursor 2960 return await self._http.request( 2961 f"/api/v1/users/{user}/tasks/blocker_cycles", 2962 query=query, 2963 response_type=UserTaskBlockerCyclesResponse, 2964 ) 2965 2966 async def ready( 2967 self, 2968 user: str, 2969 *, 2970 team: str | None = None, 2971 org: str | None = None, 2972 explain: bool | None = None, 2973 assigned_to_me: bool | None = None, 2974 source_scope: str | None = None, 2975 source_type: str | None = None, 2976 source_id: str | None = None, 2977 epic: str | None = None, 2978 limit: int | None = None, 2979 after_cursor: str | None = None, 2980 ) -> UserTaskReadyResponse: 2981 """ 2982 List an owner's ready tasks 2983 Returns open tasks with no unfinished blockers and no active session lease. 2984 Readiness is calculated by the server from the current task projection. It is 2985 a snapshot, not a reservation; claim a task lease before starting work. 2986 Pass `explain=true` to include every open task with a stable readiness reason. 2987 2988 Args: 2989 user: User ID (`usr_...`) for user-scoped tasks. 2990 team: Team ID (`tem_...`) owning the tasks. 2991 org: Optional organization context for privileged callers. 2992 explain: Include blocked and actively leased open tasks with exclusion reasons. 2993 assigned_to_me: Only include tasks assigned to the authenticated user. 2994 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 2995 source_type: Only include tasks whose source matches this object kind. 2996 source_id: Only include tasks whose source matches this object identity. 2997 epic: Only include tasks with this exact epic label. 2998 limit: Maximum number of readiness entries to return. Capped at 100. 2999 after_cursor: Opaque cursor returned by the previous page. 3000 3001 Returns: 3002 Successful response 3003 """ 3004 query: dict[str, object] = {} 3005 if team is not None: 3006 query["team"] = team 3007 if org is not None: 3008 query["org"] = org 3009 if explain is not None: 3010 query["explain"] = explain 3011 if assigned_to_me is not None: 3012 query["assigned_to_me"] = assigned_to_me 3013 if source_scope is not None: 3014 query["source_scope"] = source_scope 3015 if source_type is not None: 3016 query["source_type"] = source_type 3017 if source_id is not None: 3018 query["source_id"] = source_id 3019 if epic is not None: 3020 query["epic"] = epic 3021 if limit is not None: 3022 query["limit"] = limit 3023 if after_cursor is not None: 3024 query["after_cursor"] = after_cursor 3025 return await self._http.request( 3026 f"/api/v1/users/{user}/tasks/ready", 3027 query=query, 3028 response_type=UserTaskReadyResponse, 3029 ) 3030 3031 async def search( 3032 self, 3033 user: str, 3034 *, 3035 team: str | None = None, 3036 org: str | None = None, 3037 q: str | None = None, 3038 query: str | None = None, 3039 status: str | None = None, 3040 owner_user: str | None = None, 3041 owner_agent: str | None = None, 3042 priority: int | None = None, 3043 tag: str | None = None, 3044 parent: str | None = None, 3045 source_scope: str | None = None, 3046 source_type: str | None = None, 3047 source_id: str | None = None, 3048 epic: str | None = None, 3049 limit: int | None = None, 3050 after_cursor: str | None = None, 3051 ) -> UserTaskSearchResponse: 3052 """ 3053 Search an owner's tasks 3054 Performs a full-text search over tasks owned by the specified user or team and returns 3055 matching results. Combine `q` with the optional filters to narrow the result set 3056 further. When no query is provided, the endpoint behaves like a filtered list. 3057 The `query` field in the response echoes the effective search query. 3058 User-authenticated callers may search their personal tasks or tasks for teams 3059 they have joined. Privileged callers provide the owner in the route; the owner's 3060 organization is implied by that principal. An explicit `org` is optional and, 3061 when set, must match the owner's organization. 3062 3063 Args: 3064 user: User ID (`usr_...`) for user-scoped tasks. 3065 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3066 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3067 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3068 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3069 status: Filter results by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to include all statuses. 3070 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3071 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3072 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3073 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3074 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3075 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3076 source_type: Return only tasks whose source matches this object kind. 3077 source_id: Return only tasks whose source matches this object identity. 3078 epic: Return only tasks with this exact epic label. 3079 limit: Maximum number of tasks to return. Capped at 100. 3080 after_cursor: Opaque cursor returned by the previous page. 3081 3082 Returns: 3083 Successful response 3084 """ 3085 query: dict[str, object] = {} 3086 if team is not None: 3087 query["team"] = team 3088 if org is not None: 3089 query["org"] = org 3090 if q is not None: 3091 query["q"] = q 3092 if query is not None: 3093 query["query"] = query 3094 if status is not None: 3095 query["status"] = status 3096 if owner_user is not None: 3097 query["owner_user"] = owner_user 3098 if owner_agent is not None: 3099 query["owner_agent"] = owner_agent 3100 if priority is not None: 3101 query["priority"] = priority 3102 if tag is not None: 3103 query["tag"] = tag 3104 if parent is not None: 3105 query["parent"] = parent 3106 if source_scope is not None: 3107 query["source_scope"] = source_scope 3108 if source_type is not None: 3109 query["source_type"] = source_type 3110 if source_id is not None: 3111 query["source_id"] = source_id 3112 if epic is not None: 3113 query["epic"] = epic 3114 if limit is not None: 3115 query["limit"] = limit 3116 if after_cursor is not None: 3117 query["after_cursor"] = after_cursor 3118 return await self._http.request( 3119 f"/api/v1/users/{user}/tasks/search", 3120 query=query, 3121 response_type=UserTaskSearchResponse, 3122 )
AsyncUserTaskResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, user: str, *, team: str | None = None, org: 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, 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, limit: int | None = None, after_cursor: str | None = None) -> UserTaskListResponse:
2782 async def list( 2783 self, 2784 user: str, 2785 *, 2786 team: str | None = None, 2787 org: str | None = None, 2788 status: str | None = None, 2789 owner_user: str | None = None, 2790 owner_agent: str | None = None, 2791 priority: int | None = None, 2792 tag: str | None = None, 2793 parent: str | None = None, 2794 source_scope: str | None = None, 2795 source_type: str | None = None, 2796 source_id: str | None = None, 2797 epic: str | None = None, 2798 search: str | None = None, 2799 sort: str | None = None, 2800 order: str | None = None, 2801 due_before: str | None = None, 2802 due_after: str | None = None, 2803 overdue: bool | None = None, 2804 ready: bool | None = None, 2805 limit: int | None = None, 2806 after_cursor: str | None = None, 2807 ) -> UserTaskListResponse: 2808 """ 2809 List an owner's tasks 2810 Returns tasks owned by the specified user or team. You can narrow results using the 2811 optional filters below. By default results are returned in reverse chronological 2812 order (most recently created first); use `sort` and `order` to sort by due date or 2813 priority instead. 2814 User-authenticated callers may list their personal tasks or tasks for teams they 2815 have joined. Privileged callers provide the owner in the route; the owner's 2816 organization is implied by that principal. An explicit `org` is optional and, 2817 when set, must match the owner's organization. 2818 2819 Args: 2820 user: User ID (`usr_...`) for user-scoped tasks. 2821 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 2822 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 2823 status: Filter tasks by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to return tasks in all statuses. 2824 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 2825 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 2826 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 2827 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 2828 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 2829 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 2830 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 2831 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 2832 epic: Return only tasks with this exact epic label. 2833 search: Restrict results to tasks whose name or description contains this string. 2834 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. 2835 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 2836 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. 2837 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 2838 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. 2839 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. 2840 limit: Maximum number of tasks to return. Capped at 100. 2841 after_cursor: Opaque cursor returned by the previous page. 2842 2843 Returns: 2844 Successful response 2845 """ 2846 query: dict[str, object] = {} 2847 if team is not None: 2848 query["team"] = team 2849 if org is not None: 2850 query["org"] = org 2851 if status is not None: 2852 query["status"] = status 2853 if owner_user is not None: 2854 query["owner_user"] = owner_user 2855 if owner_agent is not None: 2856 query["owner_agent"] = owner_agent 2857 if priority is not None: 2858 query["priority"] = priority 2859 if tag is not None: 2860 query["tag"] = tag 2861 if parent is not None: 2862 query["parent"] = parent 2863 if source_scope is not None: 2864 query["source_scope"] = source_scope 2865 if source_type is not None: 2866 query["source_type"] = source_type 2867 if source_id is not None: 2868 query["source_id"] = source_id 2869 if epic is not None: 2870 query["epic"] = epic 2871 if search is not None: 2872 query["search"] = search 2873 if sort is not None: 2874 query["sort"] = sort 2875 if order is not None: 2876 query["order"] = order 2877 if due_before is not None: 2878 query["due_before"] = due_before 2879 if due_after is not None: 2880 query["due_after"] = due_after 2881 if overdue is not None: 2882 query["overdue"] = overdue 2883 if ready is not None: 2884 query["ready"] = ready 2885 if limit is not None: 2886 query["limit"] = limit 2887 if after_cursor is not None: 2888 query["after_cursor"] = after_cursor 2889 return await self._http.request( 2890 f"/api/v1/users/{user}/tasks", 2891 query=query, 2892 response_type=UserTaskListResponse, 2893 )
List an owner's tasks
Returns tasks owned by the specified user or team. You can narrow results using the
optional filters below. By default results are returned in reverse chronological
order (most recently created first); use sort and order to sort by due date or
priority instead.
User-authenticated callers may list their personal tasks or tasks for teams they
have joined. Privileged callers provide the owner in the route; the owner's
organization is implied by that principal. An explicit org is optional and,
when set, must match the owner's organization.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...). Only tasks belonging to this team are returned. - org: Optional organization (
org_...) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. - status: Filter tasks by status. One of
"open","in_progress", 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.
- 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, user: str, input: UserTaskCreateInput) -> archastro.platform.types.tasks.Task:
2895 async def create(self, user: str, input: UserTaskCreateInput) -> Task: 2896 """ 2897 Create a task for an owner 2898 Creates a new task owned by the specified user or team and returns the full 2899 task object. User-authenticated calls are attributed to the authenticated 2900 user or agent. App-scoped developer and server-to-server callers must provide 2901 the task's explicit `org` scope and an explicit `user` or `agent` actor for 2902 team tasks; a user-owned task reuses the user in the route unless an explicit 2903 agent is supplied. Every referenced principal is validated against the app, 2904 owner, and team membership before creation. 2905 2906 Args: 2907 user: User ID (`usr_...`) for user-scoped tasks. 2908 input: Request body. 2909 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 task owner. 2910 input.org: Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. 2911 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 2912 input.team: Team ID (`tem_...`). The task will be owned by this team. 2913 2914 Returns: 2915 The newly created task. 2916 """ 2917 return await self._http.request( 2918 f"/api/v1/users/{user}/tasks", 2919 method="POST", 2920 body=input, 2921 response_type=Task, 2922 )
Create a task for an owner
Creates a new task owned by the specified user or team and returns the full
task object. User-authenticated calls are attributed to the authenticated
user or agent. App-scoped developer and server-to-server callers must provide
the task's explicit org scope and an explicit user or agent actor for
team tasks; a user-owned task reuses the user in the route unless an explicit
agent is supplied. Every referenced principal is validated against the app,
owner, and team membership before creation.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - 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 task owner. - input.org: Explicit organization (
org_...) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. - input.task: Attributes for the task to create.
nameis required; all other fields are optional. - input.team: Team ID (
tem_...). The task will be owned by this team.
Returns:
The newly created task.
async def
blocker_cycles( self, user: str, *, team: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> UserTaskBlockerCyclesResponse:
2924 async def blocker_cycles( 2925 self, 2926 user: str, 2927 *, 2928 team: str | None = None, 2929 org: str | None = None, 2930 limit: int | None = None, 2931 after_cursor: str | None = None, 2932 ) -> UserTaskBlockerCyclesResponse: 2933 """ 2934 List task blocker cycles 2935 Runs an on-demand diagnostic over unfinished tasks owned by the specified 2936 team or user and returns a forward cursor-paginated page of complete cyclic 2937 blocker components. Detection is bounded to owners with at most 100 2938 unfinished tasks. This endpoint is read-only: cycles do not prevent task 2939 updates, lease acquisition, or completion. 2940 2941 Args: 2942 user: User ID (`usr_...`) for user-scoped tasks. 2943 team: Team ID (`tem_...`) owning the tasks. 2944 org: Optional organization context for privileged callers. 2945 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 2946 after_cursor: Opaque cursor returned by the preceding page. 2947 2948 Returns: 2949 Successful response 2950 """ 2951 query: dict[str, object] = {} 2952 if team is not None: 2953 query["team"] = team 2954 if org is not None: 2955 query["org"] = org 2956 if limit is not None: 2957 query["limit"] = limit 2958 if after_cursor is not None: 2959 query["after_cursor"] = after_cursor 2960 return await self._http.request( 2961 f"/api/v1/users/{user}/tasks/blocker_cycles", 2962 query=query, 2963 response_type=UserTaskBlockerCyclesResponse, 2964 )
List task blocker cycles Runs an on-demand diagnostic over unfinished tasks owned by the specified team or user and returns a forward cursor-paginated page of complete cyclic blocker components. Detection is bounded to owners with at most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent task updates, lease acquisition, or completion.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...) owning the tasks. - org: Optional organization context for privileged callers.
- 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
ready( self, user: str, *, team: str | None = None, org: str | None = None, 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) -> UserTaskReadyResponse:
2966 async def ready( 2967 self, 2968 user: str, 2969 *, 2970 team: str | None = None, 2971 org: str | None = None, 2972 explain: bool | None = None, 2973 assigned_to_me: bool | None = None, 2974 source_scope: str | None = None, 2975 source_type: str | None = None, 2976 source_id: str | None = None, 2977 epic: str | None = None, 2978 limit: int | None = None, 2979 after_cursor: str | None = None, 2980 ) -> UserTaskReadyResponse: 2981 """ 2982 List an owner's ready tasks 2983 Returns open tasks with no unfinished blockers and no active session lease. 2984 Readiness is calculated by the server from the current task projection. It is 2985 a snapshot, not a reservation; claim a task lease before starting work. 2986 Pass `explain=true` to include every open task with a stable readiness reason. 2987 2988 Args: 2989 user: User ID (`usr_...`) for user-scoped tasks. 2990 team: Team ID (`tem_...`) owning the tasks. 2991 org: Optional organization context for privileged callers. 2992 explain: Include blocked and actively leased open tasks with exclusion reasons. 2993 assigned_to_me: Only include tasks assigned to the authenticated user. 2994 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 2995 source_type: Only include tasks whose source matches this object kind. 2996 source_id: Only include tasks whose source matches this object identity. 2997 epic: Only include tasks with this exact epic label. 2998 limit: Maximum number of readiness entries to return. Capped at 100. 2999 after_cursor: Opaque cursor returned by the previous page. 3000 3001 Returns: 3002 Successful response 3003 """ 3004 query: dict[str, object] = {} 3005 if team is not None: 3006 query["team"] = team 3007 if org is not None: 3008 query["org"] = org 3009 if explain is not None: 3010 query["explain"] = explain 3011 if assigned_to_me is not None: 3012 query["assigned_to_me"] = assigned_to_me 3013 if source_scope is not None: 3014 query["source_scope"] = source_scope 3015 if source_type is not None: 3016 query["source_type"] = source_type 3017 if source_id is not None: 3018 query["source_id"] = source_id 3019 if epic is not None: 3020 query["epic"] = epic 3021 if limit is not None: 3022 query["limit"] = limit 3023 if after_cursor is not None: 3024 query["after_cursor"] = after_cursor 3025 return await self._http.request( 3026 f"/api/v1/users/{user}/tasks/ready", 3027 query=query, 3028 response_type=UserTaskReadyResponse, 3029 )
List an owner's ready tasks
Returns open tasks with no unfinished blockers and no active session lease.
Readiness is calculated by the server from the current task projection. It is
a snapshot, not a reservation; claim a task lease before starting work.
Pass explain=true to include every open task with a stable readiness reason.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...) owning the tasks. - org: Optional organization context for privileged callers.
- 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, user: str, *, team: str | None = None, org: str | None = None, 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) -> UserTaskSearchResponse:
3031 async def search( 3032 self, 3033 user: str, 3034 *, 3035 team: str | None = None, 3036 org: str | None = None, 3037 q: str | None = None, 3038 query: str | None = None, 3039 status: str | None = None, 3040 owner_user: str | None = None, 3041 owner_agent: str | None = None, 3042 priority: int | None = None, 3043 tag: str | None = None, 3044 parent: str | None = None, 3045 source_scope: str | None = None, 3046 source_type: str | None = None, 3047 source_id: str | None = None, 3048 epic: str | None = None, 3049 limit: int | None = None, 3050 after_cursor: str | None = None, 3051 ) -> UserTaskSearchResponse: 3052 """ 3053 Search an owner's tasks 3054 Performs a full-text search over tasks owned by the specified user or team and returns 3055 matching results. Combine `q` with the optional filters to narrow the result set 3056 further. When no query is provided, the endpoint behaves like a filtered list. 3057 The `query` field in the response echoes the effective search query. 3058 User-authenticated callers may search their personal tasks or tasks for teams 3059 they have joined. Privileged callers provide the owner in the route; the owner's 3060 organization is implied by that principal. An explicit `org` is optional and, 3061 when set, must match the owner's organization. 3062 3063 Args: 3064 user: User ID (`usr_...`) for user-scoped tasks. 3065 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3066 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3067 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3068 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3069 status: Filter results by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to include all statuses. 3070 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3071 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3072 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3073 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3074 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3075 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3076 source_type: Return only tasks whose source matches this object kind. 3077 source_id: Return only tasks whose source matches this object identity. 3078 epic: Return only tasks with this exact epic label. 3079 limit: Maximum number of tasks to return. Capped at 100. 3080 after_cursor: Opaque cursor returned by the previous page. 3081 3082 Returns: 3083 Successful response 3084 """ 3085 query: dict[str, object] = {} 3086 if team is not None: 3087 query["team"] = team 3088 if org is not None: 3089 query["org"] = org 3090 if q is not None: 3091 query["q"] = q 3092 if query is not None: 3093 query["query"] = query 3094 if status is not None: 3095 query["status"] = status 3096 if owner_user is not None: 3097 query["owner_user"] = owner_user 3098 if owner_agent is not None: 3099 query["owner_agent"] = owner_agent 3100 if priority is not None: 3101 query["priority"] = priority 3102 if tag is not None: 3103 query["tag"] = tag 3104 if parent is not None: 3105 query["parent"] = parent 3106 if source_scope is not None: 3107 query["source_scope"] = source_scope 3108 if source_type is not None: 3109 query["source_type"] = source_type 3110 if source_id is not None: 3111 query["source_id"] = source_id 3112 if epic is not None: 3113 query["epic"] = epic 3114 if limit is not None: 3115 query["limit"] = limit 3116 if after_cursor is not None: 3117 query["after_cursor"] = after_cursor 3118 return await self._http.request( 3119 f"/api/v1/users/{user}/tasks/search", 3120 query=query, 3121 response_type=UserTaskSearchResponse, 3122 )
Search an owner's tasks
Performs a full-text search over tasks owned by the specified user or team and returns
matching results. Combine q with the optional filters to narrow the result set
further. When no query is provided, the endpoint behaves like a filtered list.
The query field in the response echoes the effective search query.
User-authenticated callers may search their personal tasks or tasks for teams
they have joined. Privileged callers provide the owner in the route; the owner's
organization is implied by that principal. An explicit org is optional and,
when set, must match the owner's organization.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...). Only tasks belonging to this team are searched. - org: Optional organization (
org_...) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. - 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", or"done". Omit to include all statuses. - owner_user: Restrict results to tasks assigned to the user with this public ID (
usr_...). - owner_agent: Restrict results to tasks assigned to the agent with this public ID (
agi_...). - priority: Filter results 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.
- source_id: Return only tasks whose source matches this object identity.
- 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
AsyncUserThreadResource:
3125class AsyncUserThreadResource: 3126 def __init__(self, http: HttpClient): 3127 self._http = http 3128 3129 async def list( 3130 self, 3131 user: str, 3132 *, 3133 agent: builtins.list[str] | None = None, 3134 filter: builtins.list[dict[str, Any]] | None = None, 3135 ) -> UserThreadListResponse: 3136 """ 3137 List threads for a user 3138 Returns all threads visible to the specified user. The authenticated caller must 3139 have access to the target user's account; a 403 is returned otherwise. 3140 Pass one or more `agent` IDs to narrow results to threads where at least one of 3141 the listed agents is also a member useful for displaying every thread a user 3142 shares with a particular agent. Pass one or more `filter` objects to narrow 3143 results by thread metadata key/value pairs. Both narrowings may be combined in 3144 a single request. 3145 Results are returned as a flat array; no cursor-based pagination is applied. 3146 Threads are ordered with default threads first, then by most recent activity 3147 (newest first), each carrying a `last_activity` timestamp. 3148 3149 Args: 3150 user: User ID (`usr_...`) whose threads should be listed. 3151 agent: Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. 3152 filter: Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata. 3153 3154 Returns: 3155 Successful response 3156 """ 3157 query: dict[str, object] = {} 3158 if agent is not None: 3159 query["agent"] = agent 3160 if filter is not None: 3161 query["filter"] = filter 3162 return await self._http.request( 3163 f"/api/v1/users/{user}/threads", 3164 query=query, 3165 response_type=UserThreadListResponse, 3166 ) 3167 3168 async def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3169 """ 3170 Create a thread for a user 3171 Creates a new thread owned by the specified user. The authenticated caller must 3172 have access to the target user's account; a 403 is returned otherwise. 3173 An automatic welcome message is sent into the thread upon creation unless 3174 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3175 the owning user and any members added at creation time. 3176 3177 Args: 3178 user: User ID (`usr_...`) whose threads should be listed. 3179 input: Request body. 3180 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3181 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3182 3183 Returns: 3184 The newly created thread object. 3185 """ 3186 return await self._http.request( 3187 f"/api/v1/users/{user}/threads", 3188 method="POST", 3189 body=input, 3190 response_type=Thread, 3191 )
AsyncUserThreadResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, user: str, *, agent: list[str] | None = None, filter: list[dict[str, typing.Any]] | None = None) -> UserThreadListResponse:
3129 async def list( 3130 self, 3131 user: str, 3132 *, 3133 agent: builtins.list[str] | None = None, 3134 filter: builtins.list[dict[str, Any]] | None = None, 3135 ) -> UserThreadListResponse: 3136 """ 3137 List threads for a user 3138 Returns all threads visible to the specified user. The authenticated caller must 3139 have access to the target user's account; a 403 is returned otherwise. 3140 Pass one or more `agent` IDs to narrow results to threads where at least one of 3141 the listed agents is also a member useful for displaying every thread a user 3142 shares with a particular agent. Pass one or more `filter` objects to narrow 3143 results by thread metadata key/value pairs. Both narrowings may be combined in 3144 a single request. 3145 Results are returned as a flat array; no cursor-based pagination is applied. 3146 Threads are ordered with default threads first, then by most recent activity 3147 (newest first), each carrying a `last_activity` timestamp. 3148 3149 Args: 3150 user: User ID (`usr_...`) whose threads should be listed. 3151 agent: Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. 3152 filter: Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata. 3153 3154 Returns: 3155 Successful response 3156 """ 3157 query: dict[str, object] = {} 3158 if agent is not None: 3159 query["agent"] = agent 3160 if filter is not None: 3161 query["filter"] = filter 3162 return await self._http.request( 3163 f"/api/v1/users/{user}/threads", 3164 query=query, 3165 response_type=UserThreadListResponse, 3166 )
List threads for a user
Returns all threads visible to the specified user. The authenticated caller must
have access to the target user's account; a 403 is returned otherwise.
Pass one or more agent IDs to narrow results to threads where at least one of
the listed agents is also a member useful for displaying every thread a user
shares with a particular agent. Pass one or more filter objects to narrow
results by thread metadata key/value pairs. Both narrowings may be combined in
a single request.
Results are returned as a flat array; no cursor-based pagination is applied.
Threads are ordered with default threads first, then by most recent activity
(newest first), each carrying a last_activity timestamp.
Arguments:
- user: User ID (
usr_...) whose threads should be listed. - agent: Array of agent user IDs (
usr_...). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. - filter: Array of metadata filter objects. Each filter matches threads whose
metadatamap contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata.
Returns:
Successful response
async def
create( self, user: str, input: UserThreadCreateInput) -> archastro.platform.types.threads.Thread:
3168 async def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3169 """ 3170 Create a thread for a user 3171 Creates a new thread owned by the specified user. The authenticated caller must 3172 have access to the target user's account; a 403 is returned otherwise. 3173 An automatic welcome message is sent into the thread upon creation unless 3174 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3175 the owning user and any members added at creation time. 3176 3177 Args: 3178 user: User ID (`usr_...`) whose threads should be listed. 3179 input: Request body. 3180 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3181 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3182 3183 Returns: 3184 The newly created thread object. 3185 """ 3186 return await self._http.request( 3187 f"/api/v1/users/{user}/threads", 3188 method="POST", 3189 body=input, 3190 response_type=Thread, 3191 )
Create a thread for a user
Creates a new thread owned by the specified user. The authenticated caller must
have access to the target user's account; a 403 is returned otherwise.
An automatic welcome message is sent into the thread upon creation unless
skip_welcome_message is set to true. The thread is immediately visible to
the owning user and any members added at creation time.
Arguments:
- user: User ID (
usr_...) whose 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. See ThreadCreateParams for the full set of accepted fields.
Returns:
The newly created thread object.
class
AsyncTokenResource:
3194class AsyncTokenResource: 3195 def __init__(self, http: HttpClient): 3196 self._http = http 3197 3198 async def list(self, user: str) -> TokenListResponse: 3199 """ 3200 List personal access tokens 3201 Returns all access tokens associated with the authenticated user, including 3202 active and revoked tokens. Tokens are returned without their raw JWT values 3203 the plaintext JWT is only available at creation time. 3204 The caller must be the user identified by `user` and must present a 3205 first-party session (or a `full_access` access token). 3206 3207 Args: 3208 user: User ID (`usr_...`) or `me` for the authenticated user. 3209 3210 Returns: 3211 Successful response 3212 """ 3213 return await self._http.request( 3214 f"/api/v1/users/{user}/tokens", 3215 response_type=TokenListResponse, 3216 ) 3217 3218 async def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3219 """ 3220 Create a personal access token 3221 Issues a new long-lived access token for the authenticated user. The raw 3222 JWT is returned in the `token` field of the response exactly once and 3223 cannot be retrieved again store it securely immediately after creation. 3224 `scopes` is optional. When omitted the token receives `full_access`. 3225 Known catalog scopes (for example `profile`) restrict the token through 3226 the same `ScopeGuard` used by OAuth. 3227 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3228 or `365`. When omitted the token lasts 30 days. Each user may hold at 3229 most 50 active tokens; exceeding that limit returns 429. 3230 The caller must be the user identified by `user` and must present a 3231 first-party session (or a `full_access` access token). A restricted 3232 access token cannot mint another token. 3233 3234 Args: 3235 user: User ID (`usr_...`) or `me` for the authenticated user. 3236 input: Request body. 3237 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3238 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3239 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3240 3241 Returns: 3242 The newly created access token. The `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. 3243 """ 3244 return await self._http.request( 3245 f"/api/v1/users/{user}/tokens", 3246 method="POST", 3247 body=input, 3248 response_type=SystemAccessToken, 3249 ) 3250 3251 async def delete(self, user: str, token: str) -> SystemAccessToken: 3252 """ 3253 Revoke a personal access token 3254 Permanently revokes the specified access token belonging to the 3255 authenticated user. Once revoked, the token is immediately rejected by 3256 all API endpoints and cannot be reinstated. The token record is retained 3257 and returned in the response with `revoked_at` populated. 3258 The caller must be the user identified by `user` and must present a 3259 first-party session (or a `full_access` access token). Returns 404 if 3260 the token does not exist or does not belong to the caller. 3261 3262 Args: 3263 user: User ID (`usr_...`) or `me` for the authenticated user. 3264 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3265 3266 Returns: 3267 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3268 """ 3269 return await self._http.request( 3270 f"/api/v1/users/{user}/tokens/{token}", 3271 method="DELETE", 3272 response_type=SystemAccessToken, 3273 )
AsyncTokenResource(http: archastro.platform.runtime.http_client.HttpClient)
3198 async def list(self, user: str) -> TokenListResponse: 3199 """ 3200 List personal access tokens 3201 Returns all access tokens associated with the authenticated user, including 3202 active and revoked tokens. Tokens are returned without their raw JWT values 3203 the plaintext JWT is only available at creation time. 3204 The caller must be the user identified by `user` and must present a 3205 first-party session (or a `full_access` access token). 3206 3207 Args: 3208 user: User ID (`usr_...`) or `me` for the authenticated user. 3209 3210 Returns: 3211 Successful response 3212 """ 3213 return await self._http.request( 3214 f"/api/v1/users/{user}/tokens", 3215 response_type=TokenListResponse, 3216 )
List personal access tokens
Returns all access tokens associated with the authenticated user, including
active and revoked tokens. Tokens are returned without their raw JWT values
the plaintext JWT is only available at creation time.
The caller must be the user identified by user and must present a
first-party session (or a full_access access token).
Arguments:
- user: User ID (
usr_...) ormefor the authenticated user.
Returns:
Successful response
async def
create( self, user: str, input: TokenCreateInput) -> archastro.platform.types.system.SystemAccessToken:
3218 async def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3219 """ 3220 Create a personal access token 3221 Issues a new long-lived access token for the authenticated user. The raw 3222 JWT is returned in the `token` field of the response exactly once and 3223 cannot be retrieved again store it securely immediately after creation. 3224 `scopes` is optional. When omitted the token receives `full_access`. 3225 Known catalog scopes (for example `profile`) restrict the token through 3226 the same `ScopeGuard` used by OAuth. 3227 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3228 or `365`. When omitted the token lasts 30 days. Each user may hold at 3229 most 50 active tokens; exceeding that limit returns 429. 3230 The caller must be the user identified by `user` and must present a 3231 first-party session (or a `full_access` access token). A restricted 3232 access token cannot mint another token. 3233 3234 Args: 3235 user: User ID (`usr_...`) or `me` for the authenticated user. 3236 input: Request body. 3237 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3238 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3239 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3240 3241 Returns: 3242 The newly created access token. The `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. 3243 """ 3244 return await self._http.request( 3245 f"/api/v1/users/{user}/tokens", 3246 method="POST", 3247 body=input, 3248 response_type=SystemAccessToken, 3249 )
Create a personal access token
Issues a new long-lived access token for the authenticated user. The raw
JWT is returned in the token field of the response exactly once and
cannot be retrieved again store it securely immediately after creation.
scopes is optional. When omitted the token receives full_access.
Known catalog scopes (for example profile) restrict the token through
the same ScopeGuard used by OAuth.
expires_in_days is optional and must be one of 7, 30, 60, 90,
or 365. When omitted the token lasts 30 days. Each user may hold at
most 50 active tokens; exceeding that limit returns 429.
The caller must be the user identified by user and must present a
first-party session (or a full_access access token). A restricted
access token cannot mint another token.
Arguments:
- user: User ID (
usr_...) ormefor the authenticated user. - input: Request body.
- input.expires_in_days: Lifetime in days. One of
7,30,60,90, or365. Defaults to30. - input.name: Human-readable label for the token (e.g.
"Codex MCP"). Stored as metadata only. - input.scopes: Optional OAuth scopes to stamp on the token. Omit for
full_access.
Returns:
The newly created access token. The
tokenfield contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later.
async def
delete( self, user: str, token: str) -> archastro.platform.types.system.SystemAccessToken:
3251 async def delete(self, user: str, token: str) -> SystemAccessToken: 3252 """ 3253 Revoke a personal access token 3254 Permanently revokes the specified access token belonging to the 3255 authenticated user. Once revoked, the token is immediately rejected by 3256 all API endpoints and cannot be reinstated. The token record is retained 3257 and returned in the response with `revoked_at` populated. 3258 The caller must be the user identified by `user` and must present a 3259 first-party session (or a `full_access` access token). Returns 404 if 3260 the token does not exist or does not belong to the caller. 3261 3262 Args: 3263 user: User ID (`usr_...`) or `me` for the authenticated user. 3264 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3265 3266 Returns: 3267 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3268 """ 3269 return await self._http.request( 3270 f"/api/v1/users/{user}/tokens/{token}", 3271 method="DELETE", 3272 response_type=SystemAccessToken, 3273 )
Revoke a personal access token
Permanently revokes the specified access token belonging to the
authenticated user. Once revoked, the token is immediately rejected by
all API endpoints and cannot be reinstated. The token record is retained
and returned in the response with revoked_at populated.
The caller must be the user identified by user and must present a
first-party session (or a full_access access token). Returns 404 if
the token does not exist or does not belong to the caller.
Arguments:
- user: User ID (
usr_...) ormefor the authenticated user. - token: Access token ID (
sat_...). Must belong to the authenticated user.
Returns:
The revoked access token. The
revoked_atfield is populated with the time of revocation.
class
AsyncUserResource:
3276class AsyncUserResource: 3277 def __init__(self, http: HttpClient): 3278 self._http = http 3279 self.tasks = AsyncUserTaskResource(http) 3280 self.threads = AsyncUserThreadResource(http) 3281 self.tokens = AsyncTokenResource(http) 3282 3283 async def me(self) -> User: 3284 """ 3285 Retrieve the current user 3286 Returns the user associated with the authenticated session or bearer 3287 token. This is the canonical way to resolve "who am I?" after 3288 authentication. 3289 The response includes the user's profile, notification settings, and 3290 profile picture, along with the app, organization, and sandbox the 3291 token is scoped to and their display names enough to establish full 3292 session context in a single call. Unauthenticated requests return 401. 3293 3294 Returns: 3295 The authenticated user object. 3296 """ 3297 return await self._http.request("/api/v1/users/me", response_type=User) 3298 3299 async def get(self, user: str) -> User: 3300 """ 3301 Retrieve a user by ID 3302 Returns the user identified by `user`. The authenticated user must share 3303 at least one team with the target user; requests for users outside any 3304 shared team are rejected with 403. 3305 A user may always retrieve their own profile with this endpoint. Use the 3306 `GET /users/me` endpoint as a convenience alias for retrieving the 3307 authenticated user without specifying an ID. 3308 3309 Args: 3310 user: User ID (`usr_...`) of the user to retrieve. 3311 3312 Returns: 3313 The requested user object. 3314 """ 3315 return await self._http.request(f"/api/v1/users/{user}", response_type=User) 3316 3317 async def artifacts(self, user: str) -> UserArtifactsResponse: 3318 """ 3319 List a user's artifacts 3320 Returns all artifacts owned by the specified user. Artifacts represent 3321 AI-generated or user-uploaded files associated with agent sessions, 3322 threads, or sandboxes such as images, documents, and code outputs. 3323 The authenticated user must be requesting their own artifacts or must 3324 have administrative access. Attempting to list artifacts for a user 3325 the caller is not authorized to access returns 403. 3326 Results are returned in a single page without cursor pagination. Each 3327 artifact in the response reflects the state of its current version, 3328 including a short-lived signed `file_url` for direct download. 3329 3330 Args: 3331 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3332 3333 Returns: 3334 Successful response 3335 """ 3336 return await self._http.request( 3337 f"/api/v1/users/{user}/artifacts", 3338 response_type=UserArtifactsResponse, 3339 ) 3340 3341 async def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3342 """ 3343 Create a user invite 3344 Creates a new invite for the authenticated user. The invite can optionally be 3345 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3346 caller receives the new invite object at HTTP 201. 3347 The invite key is always generated server-side (192-bit URL-safe random 3348 string) and cannot be supplied by the caller. 3349 The path `:user` must match the authenticated user. If a `thread_id` is 3350 provided, the authenticated user must have permission to invite others to that 3351 thread; team threads are not supported and return an error. Supplying a 3352 `thread_id` that does not exist or that belongs to a different user returns 3353 an error. If a key collision occurs during creation the call returns a 409 3354 conflict simply retry to generate a new key. 3355 3356 Args: 3357 user: User ID (`usr_...`). Must match the authenticated user. 3358 input: Request body. 3359 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3360 3361 Returns: 3362 The newly created invite object. 3363 """ 3364 return await self._http.request( 3365 f"/api/v1/users/{user}/invites", 3366 method="POST", 3367 body=input, 3368 response_type=UserInvite, 3369 ) 3370 3371 async def orgs(self, user: str) -> UserOrgsResponse: 3372 """ 3373 List organizations for a user 3374 Returns the organizations the specified user belongs to. A user can belong 3375 to at most one organization, so the `data` array contains either zero or one 3376 items. 3377 The authenticated viewer must have permission to inspect the target user. 3378 Returns an empty `data` array when the user has no organization membership. 3379 3380 Args: 3381 user: User ID (`usr_...`) whose organization membership you want to retrieve. 3382 3383 Returns: 3384 Successful response 3385 """ 3386 return await self._http.request( 3387 f"/api/v1/users/{user}/orgs", 3388 response_type=UserOrgsResponse, 3389 ) 3390 3391 async def profile(self, user: str, input: UserProfileInput) -> User: 3392 """ 3393 Update the current user's profile 3394 Updates one or more profile fields for the authenticated user. All 3395 fields are optional; omit any you do not want to change. 3396 When `profile_picture` is supplied, the image is uploaded and replaces 3397 the existing picture. The previous picture is deleted after the new one 3398 is stored. Image upload failures return 422 without modifying other 3399 profile fields. 3400 3401 Args: 3402 user: User ID (`usr_...`) or `"me"` for the authenticated user. 3403 input: Request body. 3404 input.alias: Short display alias shown in place of the full name in compact UI contexts. 3405 input.full_name: Updated display name for the user. 3406 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 3407 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 3408 3409 Returns: 3410 The user object with updated profile fields. 3411 """ 3412 return await self._http.request( 3413 f"/api/v1/users/{user}/profile", 3414 method="PUT", 3415 body=input, 3416 response_type=User, 3417 )
AsyncUserResource(http: archastro.platform.runtime.http_client.HttpClient)
3283 async def me(self) -> User: 3284 """ 3285 Retrieve the current user 3286 Returns the user associated with the authenticated session or bearer 3287 token. This is the canonical way to resolve "who am I?" after 3288 authentication. 3289 The response includes the user's profile, notification settings, and 3290 profile picture, along with the app, organization, and sandbox the 3291 token is scoped to and their display names enough to establish full 3292 session context in a single call. Unauthenticated requests return 401. 3293 3294 Returns: 3295 The authenticated user object. 3296 """ 3297 return await self._http.request("/api/v1/users/me", response_type=User)
Retrieve the current user Returns the user associated with the authenticated session or bearer token. This is the canonical way to resolve "who am I?" after authentication. The response includes the user's profile, notification settings, and profile picture, along with the app, organization, and sandbox the token is scoped to and their display names enough to establish full session context in a single call. Unauthenticated requests return 401.
Returns:
The authenticated user object.
3299 async def get(self, user: str) -> User: 3300 """ 3301 Retrieve a user by ID 3302 Returns the user identified by `user`. The authenticated user must share 3303 at least one team with the target user; requests for users outside any 3304 shared team are rejected with 403. 3305 A user may always retrieve their own profile with this endpoint. Use the 3306 `GET /users/me` endpoint as a convenience alias for retrieving the 3307 authenticated user without specifying an ID. 3308 3309 Args: 3310 user: User ID (`usr_...`) of the user to retrieve. 3311 3312 Returns: 3313 The requested user object. 3314 """ 3315 return await self._http.request(f"/api/v1/users/{user}", response_type=User)
Retrieve a user by ID
Returns the user identified by user. The authenticated user must share
at least one team with the target user; requests for users outside any
shared team are rejected with 403.
A user may always retrieve their own profile with this endpoint. Use the
GET /users/me endpoint as a convenience alias for retrieving the
authenticated user without specifying an ID.
Arguments:
- user: User ID (
usr_...) of the user to retrieve.
Returns:
The requested user object.
3317 async def artifacts(self, user: str) -> UserArtifactsResponse: 3318 """ 3319 List a user's artifacts 3320 Returns all artifacts owned by the specified user. Artifacts represent 3321 AI-generated or user-uploaded files associated with agent sessions, 3322 threads, or sandboxes such as images, documents, and code outputs. 3323 The authenticated user must be requesting their own artifacts or must 3324 have administrative access. Attempting to list artifacts for a user 3325 the caller is not authorized to access returns 403. 3326 Results are returned in a single page without cursor pagination. Each 3327 artifact in the response reflects the state of its current version, 3328 including a short-lived signed `file_url` for direct download. 3329 3330 Args: 3331 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3332 3333 Returns: 3334 Successful response 3335 """ 3336 return await self._http.request( 3337 f"/api/v1/users/{user}/artifacts", 3338 response_type=UserArtifactsResponse, 3339 )
List a user's artifacts
Returns all artifacts owned by the specified user. Artifacts represent
AI-generated or user-uploaded files associated with agent sessions,
threads, or sandboxes such as images, documents, and code outputs.
The authenticated user must be requesting their own artifacts or must
have administrative access. Attempting to list artifacts for a user
the caller is not authorized to access returns 403.
Results are returned in a single page without cursor pagination. Each
artifact in the response reflects the state of its current version,
including a short-lived signed file_url for direct download.
Arguments:
- user: User ID (
usr_...). The authenticated user must be this user or have access to their artifacts.
Returns:
Successful response
async def
invites( self, user: str, input: UserInvitesInput) -> archastro.platform.types.users.UserInvite:
3341 async def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3342 """ 3343 Create a user invite 3344 Creates a new invite for the authenticated user. The invite can optionally be 3345 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3346 caller receives the new invite object at HTTP 201. 3347 The invite key is always generated server-side (192-bit URL-safe random 3348 string) and cannot be supplied by the caller. 3349 The path `:user` must match the authenticated user. If a `thread_id` is 3350 provided, the authenticated user must have permission to invite others to that 3351 thread; team threads are not supported and return an error. Supplying a 3352 `thread_id` that does not exist or that belongs to a different user returns 3353 an error. If a key collision occurs during creation the call returns a 409 3354 conflict simply retry to generate a new key. 3355 3356 Args: 3357 user: User ID (`usr_...`). Must match the authenticated user. 3358 input: Request body. 3359 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3360 3361 Returns: 3362 The newly created invite object. 3363 """ 3364 return await self._http.request( 3365 f"/api/v1/users/{user}/invites", 3366 method="POST", 3367 body=input, 3368 response_type=UserInvite, 3369 )
Create a user invite
Creates a new invite for the authenticated user. The invite can optionally be
scoped to a specific thread, a persona, or carry arbitrary metadata. The
caller receives the new invite object at HTTP 201.
The invite key is always generated server-side (192-bit URL-safe random
string) and cannot be supplied by the caller.
The path :user must match the authenticated user. If a thread_id is
provided, the authenticated user must have permission to invite others to that
thread; team threads are not supported and return an error. Supplying a
thread_id that does not exist or that belongs to a different user returns
an error. If a key collision occurs during creation the call returns a 409
conflict simply retry to generate a new key.
Arguments:
- user: User ID (
usr_...). Must match the authenticated user. - input: Request body.
- input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details.
Returns:
The newly created invite object.
3371 async def orgs(self, user: str) -> UserOrgsResponse: 3372 """ 3373 List organizations for a user 3374 Returns the organizations the specified user belongs to. A user can belong 3375 to at most one organization, so the `data` array contains either zero or one 3376 items. 3377 The authenticated viewer must have permission to inspect the target user. 3378 Returns an empty `data` array when the user has no organization membership. 3379 3380 Args: 3381 user: User ID (`usr_...`) whose organization membership you want to retrieve. 3382 3383 Returns: 3384 Successful response 3385 """ 3386 return await self._http.request( 3387 f"/api/v1/users/{user}/orgs", 3388 response_type=UserOrgsResponse, 3389 )
List organizations for a user
Returns the organizations the specified user belongs to. A user can belong
to at most one organization, so the data array contains either zero or one
items.
The authenticated viewer must have permission to inspect the target user.
Returns an empty data array when the user has no organization membership.
Arguments:
- user: User ID (
usr_...) whose organization membership you want to retrieve.
Returns:
Successful response
async def
profile( self, user: str, input: UserProfileInput) -> archastro.platform.types.users.User:
3391 async def profile(self, user: str, input: UserProfileInput) -> User: 3392 """ 3393 Update the current user's profile 3394 Updates one or more profile fields for the authenticated user. All 3395 fields are optional; omit any you do not want to change. 3396 When `profile_picture` is supplied, the image is uploaded and replaces 3397 the existing picture. The previous picture is deleted after the new one 3398 is stored. Image upload failures return 422 without modifying other 3399 profile fields. 3400 3401 Args: 3402 user: User ID (`usr_...`) or `"me"` for the authenticated user. 3403 input: Request body. 3404 input.alias: Short display alias shown in place of the full name in compact UI contexts. 3405 input.full_name: Updated display name for the user. 3406 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 3407 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 3408 3409 Returns: 3410 The user object with updated profile fields. 3411 """ 3412 return await self._http.request( 3413 f"/api/v1/users/{user}/profile", 3414 method="PUT", 3415 body=input, 3416 response_type=User, 3417 )
Update the current user's profile
Updates one or more profile fields for the authenticated user. All
fields are optional; omit any you do not want to change.
When profile_picture is supplied, the image is uploaded and replaces
the existing picture. The previous picture is deleted after the new one
is stored. Image upload failures return 422 without modifying other
profile fields.
Arguments:
- user: User ID (
usr_...) or"me"for the authenticated user. - input: Request body.
- input.alias: Short display alias shown in place of the full name in compact UI contexts.
- input.full_name: Updated display name for the user.
- input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass
nullfor a key to remove it. - input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture.
Returns:
The user object with updated profile fields.
class
UserTaskResource:
3420class UserTaskResource: 3421 def __init__(self, http: SyncHttpClient): 3422 self._http = http 3423 3424 def list( 3425 self, 3426 user: str, 3427 *, 3428 team: str | None = None, 3429 org: str | None = None, 3430 status: str | None = None, 3431 owner_user: str | None = None, 3432 owner_agent: str | None = None, 3433 priority: int | None = None, 3434 tag: str | None = None, 3435 parent: str | None = None, 3436 source_scope: str | None = None, 3437 source_type: str | None = None, 3438 source_id: str | None = None, 3439 epic: str | None = None, 3440 search: str | None = None, 3441 sort: str | None = None, 3442 order: str | None = None, 3443 due_before: str | None = None, 3444 due_after: str | None = None, 3445 overdue: bool | None = None, 3446 ready: bool | None = None, 3447 limit: int | None = None, 3448 after_cursor: str | None = None, 3449 ) -> UserTaskListResponse: 3450 """ 3451 List an owner's tasks 3452 Returns tasks owned by the specified user or team. You can narrow results using the 3453 optional filters below. By default results are returned in reverse chronological 3454 order (most recently created first); use `sort` and `order` to sort by due date or 3455 priority instead. 3456 User-authenticated callers may list their personal tasks or tasks for teams they 3457 have joined. Privileged callers provide the owner in the route; the owner's 3458 organization is implied by that principal. An explicit `org` is optional and, 3459 when set, must match the owner's organization. 3460 3461 Args: 3462 user: User ID (`usr_...`) for user-scoped tasks. 3463 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 3464 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3465 status: Filter tasks by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to return tasks in all statuses. 3466 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3467 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3468 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3469 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3470 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3471 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3472 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3473 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3474 epic: Return only tasks with this exact epic label. 3475 search: Restrict results to tasks whose name or description contains this string. 3476 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. 3477 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3478 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. 3479 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3480 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. 3481 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. 3482 limit: Maximum number of tasks to return. Capped at 100. 3483 after_cursor: Opaque cursor returned by the previous page. 3484 3485 Returns: 3486 Successful response 3487 """ 3488 query: dict[str, object] = {} 3489 if team is not None: 3490 query["team"] = team 3491 if org is not None: 3492 query["org"] = org 3493 if status is not None: 3494 query["status"] = status 3495 if owner_user is not None: 3496 query["owner_user"] = owner_user 3497 if owner_agent is not None: 3498 query["owner_agent"] = owner_agent 3499 if priority is not None: 3500 query["priority"] = priority 3501 if tag is not None: 3502 query["tag"] = tag 3503 if parent is not None: 3504 query["parent"] = parent 3505 if source_scope is not None: 3506 query["source_scope"] = source_scope 3507 if source_type is not None: 3508 query["source_type"] = source_type 3509 if source_id is not None: 3510 query["source_id"] = source_id 3511 if epic is not None: 3512 query["epic"] = epic 3513 if search is not None: 3514 query["search"] = search 3515 if sort is not None: 3516 query["sort"] = sort 3517 if order is not None: 3518 query["order"] = order 3519 if due_before is not None: 3520 query["due_before"] = due_before 3521 if due_after is not None: 3522 query["due_after"] = due_after 3523 if overdue is not None: 3524 query["overdue"] = overdue 3525 if ready is not None: 3526 query["ready"] = ready 3527 if limit is not None: 3528 query["limit"] = limit 3529 if after_cursor is not None: 3530 query["after_cursor"] = after_cursor 3531 return self._http.request( 3532 f"/api/v1/users/{user}/tasks", 3533 query=query, 3534 response_type=UserTaskListResponse, 3535 ) 3536 3537 def create(self, user: str, input: UserTaskCreateInput) -> Task: 3538 """ 3539 Create a task for an owner 3540 Creates a new task owned by the specified user or team and returns the full 3541 task object. User-authenticated calls are attributed to the authenticated 3542 user or agent. App-scoped developer and server-to-server callers must provide 3543 the task's explicit `org` scope and an explicit `user` or `agent` actor for 3544 team tasks; a user-owned task reuses the user in the route unless an explicit 3545 agent is supplied. Every referenced principal is validated against the app, 3546 owner, and team membership before creation. 3547 3548 Args: 3549 user: User ID (`usr_...`) for user-scoped tasks. 3550 input: Request body. 3551 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 task owner. 3552 input.org: Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. 3553 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3554 input.team: Team ID (`tem_...`). The task will be owned by this team. 3555 3556 Returns: 3557 The newly created task. 3558 """ 3559 return self._http.request( 3560 f"/api/v1/users/{user}/tasks", 3561 method="POST", 3562 body=input, 3563 response_type=Task, 3564 ) 3565 3566 def blocker_cycles( 3567 self, 3568 user: str, 3569 *, 3570 team: str | None = None, 3571 org: str | None = None, 3572 limit: int | None = None, 3573 after_cursor: str | None = None, 3574 ) -> UserTaskBlockerCyclesResponse: 3575 """ 3576 List task blocker cycles 3577 Runs an on-demand diagnostic over unfinished tasks owned by the specified 3578 team or user and returns a forward cursor-paginated page of complete cyclic 3579 blocker components. Detection is bounded to owners with at most 100 3580 unfinished tasks. This endpoint is read-only: cycles do not prevent task 3581 updates, lease acquisition, or completion. 3582 3583 Args: 3584 user: User ID (`usr_...`) for user-scoped tasks. 3585 team: Team ID (`tem_...`) owning the tasks. 3586 org: Optional organization context for privileged callers. 3587 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3588 after_cursor: Opaque cursor returned by the preceding page. 3589 3590 Returns: 3591 Successful response 3592 """ 3593 query: dict[str, object] = {} 3594 if team is not None: 3595 query["team"] = team 3596 if org is not None: 3597 query["org"] = org 3598 if limit is not None: 3599 query["limit"] = limit 3600 if after_cursor is not None: 3601 query["after_cursor"] = after_cursor 3602 return self._http.request( 3603 f"/api/v1/users/{user}/tasks/blocker_cycles", 3604 query=query, 3605 response_type=UserTaskBlockerCyclesResponse, 3606 ) 3607 3608 def ready( 3609 self, 3610 user: str, 3611 *, 3612 team: str | None = None, 3613 org: str | None = None, 3614 explain: bool | None = None, 3615 assigned_to_me: bool | None = None, 3616 source_scope: str | None = None, 3617 source_type: str | None = None, 3618 source_id: str | None = None, 3619 epic: str | None = None, 3620 limit: int | None = None, 3621 after_cursor: str | None = None, 3622 ) -> UserTaskReadyResponse: 3623 """ 3624 List an owner's ready tasks 3625 Returns open tasks with no unfinished blockers and no active session lease. 3626 Readiness is calculated by the server from the current task projection. It is 3627 a snapshot, not a reservation; claim a task lease before starting work. 3628 Pass `explain=true` to include every open task with a stable readiness reason. 3629 3630 Args: 3631 user: User ID (`usr_...`) for user-scoped tasks. 3632 team: Team ID (`tem_...`) owning the tasks. 3633 org: Optional organization context for privileged callers. 3634 explain: Include blocked and actively leased open tasks with exclusion reasons. 3635 assigned_to_me: Only include tasks assigned to the authenticated user. 3636 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3637 source_type: Only include tasks whose source matches this object kind. 3638 source_id: Only include tasks whose source matches this object identity. 3639 epic: Only include tasks with this exact epic label. 3640 limit: Maximum number of readiness entries to return. Capped at 100. 3641 after_cursor: Opaque cursor returned by the previous page. 3642 3643 Returns: 3644 Successful response 3645 """ 3646 query: dict[str, object] = {} 3647 if team is not None: 3648 query["team"] = team 3649 if org is not None: 3650 query["org"] = org 3651 if explain is not None: 3652 query["explain"] = explain 3653 if assigned_to_me is not None: 3654 query["assigned_to_me"] = assigned_to_me 3655 if source_scope is not None: 3656 query["source_scope"] = source_scope 3657 if source_type is not None: 3658 query["source_type"] = source_type 3659 if source_id is not None: 3660 query["source_id"] = source_id 3661 if epic is not None: 3662 query["epic"] = epic 3663 if limit is not None: 3664 query["limit"] = limit 3665 if after_cursor is not None: 3666 query["after_cursor"] = after_cursor 3667 return self._http.request( 3668 f"/api/v1/users/{user}/tasks/ready", 3669 query=query, 3670 response_type=UserTaskReadyResponse, 3671 ) 3672 3673 def search( 3674 self, 3675 user: str, 3676 *, 3677 team: str | None = None, 3678 org: str | None = None, 3679 q: str | None = None, 3680 query: str | None = None, 3681 status: str | None = None, 3682 owner_user: str | None = None, 3683 owner_agent: str | None = None, 3684 priority: int | None = None, 3685 tag: str | None = None, 3686 parent: str | None = None, 3687 source_scope: str | None = None, 3688 source_type: str | None = None, 3689 source_id: str | None = None, 3690 epic: str | None = None, 3691 limit: int | None = None, 3692 after_cursor: str | None = None, 3693 ) -> UserTaskSearchResponse: 3694 """ 3695 Search an owner's tasks 3696 Performs a full-text search over tasks owned by the specified user or team and returns 3697 matching results. Combine `q` with the optional filters to narrow the result set 3698 further. When no query is provided, the endpoint behaves like a filtered list. 3699 The `query` field in the response echoes the effective search query. 3700 User-authenticated callers may search their personal tasks or tasks for teams 3701 they have joined. Privileged callers provide the owner in the route; the owner's 3702 organization is implied by that principal. An explicit `org` is optional and, 3703 when set, must match the owner's organization. 3704 3705 Args: 3706 user: User ID (`usr_...`) for user-scoped tasks. 3707 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3708 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3709 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3710 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3711 status: Filter results by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to include all statuses. 3712 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3713 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3714 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3715 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3716 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3717 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3718 source_type: Return only tasks whose source matches this object kind. 3719 source_id: Return only tasks whose source matches this object identity. 3720 epic: Return only tasks with this exact epic label. 3721 limit: Maximum number of tasks to return. Capped at 100. 3722 after_cursor: Opaque cursor returned by the previous page. 3723 3724 Returns: 3725 Successful response 3726 """ 3727 query: dict[str, object] = {} 3728 if team is not None: 3729 query["team"] = team 3730 if org is not None: 3731 query["org"] = org 3732 if q is not None: 3733 query["q"] = q 3734 if query is not None: 3735 query["query"] = query 3736 if status is not None: 3737 query["status"] = status 3738 if owner_user is not None: 3739 query["owner_user"] = owner_user 3740 if owner_agent is not None: 3741 query["owner_agent"] = owner_agent 3742 if priority is not None: 3743 query["priority"] = priority 3744 if tag is not None: 3745 query["tag"] = tag 3746 if parent is not None: 3747 query["parent"] = parent 3748 if source_scope is not None: 3749 query["source_scope"] = source_scope 3750 if source_type is not None: 3751 query["source_type"] = source_type 3752 if source_id is not None: 3753 query["source_id"] = source_id 3754 if epic is not None: 3755 query["epic"] = epic 3756 if limit is not None: 3757 query["limit"] = limit 3758 if after_cursor is not None: 3759 query["after_cursor"] = after_cursor 3760 return self._http.request( 3761 f"/api/v1/users/{user}/tasks/search", 3762 query=query, 3763 response_type=UserTaskSearchResponse, 3764 )
UserTaskResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, user: str, *, team: str | None = None, org: 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, 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, limit: int | None = None, after_cursor: str | None = None) -> UserTaskListResponse:
3424 def list( 3425 self, 3426 user: str, 3427 *, 3428 team: str | None = None, 3429 org: str | None = None, 3430 status: str | None = None, 3431 owner_user: str | None = None, 3432 owner_agent: str | None = None, 3433 priority: int | None = None, 3434 tag: str | None = None, 3435 parent: str | None = None, 3436 source_scope: str | None = None, 3437 source_type: str | None = None, 3438 source_id: str | None = None, 3439 epic: str | None = None, 3440 search: str | None = None, 3441 sort: str | None = None, 3442 order: str | None = None, 3443 due_before: str | None = None, 3444 due_after: str | None = None, 3445 overdue: bool | None = None, 3446 ready: bool | None = None, 3447 limit: int | None = None, 3448 after_cursor: str | None = None, 3449 ) -> UserTaskListResponse: 3450 """ 3451 List an owner's tasks 3452 Returns tasks owned by the specified user or team. You can narrow results using the 3453 optional filters below. By default results are returned in reverse chronological 3454 order (most recently created first); use `sort` and `order` to sort by due date or 3455 priority instead. 3456 User-authenticated callers may list their personal tasks or tasks for teams they 3457 have joined. Privileged callers provide the owner in the route; the owner's 3458 organization is implied by that principal. An explicit `org` is optional and, 3459 when set, must match the owner's organization. 3460 3461 Args: 3462 user: User ID (`usr_...`) for user-scoped tasks. 3463 team: Team ID (`tem_...`). Only tasks belonging to this team are returned. 3464 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3465 status: Filter tasks by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to return tasks in all statuses. 3466 owner_user: Filter tasks assigned to a specific user. Provide the user's public ID (`usr_...`). 3467 owner_agent: Filter tasks assigned to a specific agent. Provide the agent's public ID (`agi_...`). 3468 priority: Filter tasks by priority, from 0 (highest) to 4 (lowest). 3469 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3470 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3471 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3472 source_type: Return only tasks whose source matches this object kind. Must be supplied with the other source filters. 3473 source_id: Return only tasks whose source matches this object identity. Must be supplied with the other source filters. 3474 epic: Return only tasks with this exact epic label. 3475 search: Restrict results to tasks whose name or description contains this string. 3476 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. 3477 order: Sort direction, `"asc"` or `"desc"`. Defaults to `"desc"` for `created` and `"asc"` for `due_date` and `priority`. 3478 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. 3479 due_after: Return only tasks with a due date strictly after this ISO 8601 datetime or date. Tasks without a due date are excluded. 3480 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. 3481 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. 3482 limit: Maximum number of tasks to return. Capped at 100. 3483 after_cursor: Opaque cursor returned by the previous page. 3484 3485 Returns: 3486 Successful response 3487 """ 3488 query: dict[str, object] = {} 3489 if team is not None: 3490 query["team"] = team 3491 if org is not None: 3492 query["org"] = org 3493 if status is not None: 3494 query["status"] = status 3495 if owner_user is not None: 3496 query["owner_user"] = owner_user 3497 if owner_agent is not None: 3498 query["owner_agent"] = owner_agent 3499 if priority is not None: 3500 query["priority"] = priority 3501 if tag is not None: 3502 query["tag"] = tag 3503 if parent is not None: 3504 query["parent"] = parent 3505 if source_scope is not None: 3506 query["source_scope"] = source_scope 3507 if source_type is not None: 3508 query["source_type"] = source_type 3509 if source_id is not None: 3510 query["source_id"] = source_id 3511 if epic is not None: 3512 query["epic"] = epic 3513 if search is not None: 3514 query["search"] = search 3515 if sort is not None: 3516 query["sort"] = sort 3517 if order is not None: 3518 query["order"] = order 3519 if due_before is not None: 3520 query["due_before"] = due_before 3521 if due_after is not None: 3522 query["due_after"] = due_after 3523 if overdue is not None: 3524 query["overdue"] = overdue 3525 if ready is not None: 3526 query["ready"] = ready 3527 if limit is not None: 3528 query["limit"] = limit 3529 if after_cursor is not None: 3530 query["after_cursor"] = after_cursor 3531 return self._http.request( 3532 f"/api/v1/users/{user}/tasks", 3533 query=query, 3534 response_type=UserTaskListResponse, 3535 )
List an owner's tasks
Returns tasks owned by the specified user or team. You can narrow results using the
optional filters below. By default results are returned in reverse chronological
order (most recently created first); use sort and order to sort by due date or
priority instead.
User-authenticated callers may list their personal tasks or tasks for teams they
have joined. Privileged callers provide the owner in the route; the owner's
organization is implied by that principal. An explicit org is optional and,
when set, must match the owner's organization.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...). Only tasks belonging to this team are returned. - org: Optional organization (
org_...) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. - status: Filter tasks by status. One of
"open","in_progress", 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.
- limit: Maximum number of tasks to return. Capped at 100.
- after_cursor: Opaque cursor returned by the previous page.
Returns:
Successful response
3537 def create(self, user: str, input: UserTaskCreateInput) -> Task: 3538 """ 3539 Create a task for an owner 3540 Creates a new task owned by the specified user or team and returns the full 3541 task object. User-authenticated calls are attributed to the authenticated 3542 user or agent. App-scoped developer and server-to-server callers must provide 3543 the task's explicit `org` scope and an explicit `user` or `agent` actor for 3544 team tasks; a user-owned task reuses the user in the route unless an explicit 3545 agent is supplied. Every referenced principal is validated against the app, 3546 owner, and team membership before creation. 3547 3548 Args: 3549 user: User ID (`usr_...`) for user-scoped tasks. 3550 input: Request body. 3551 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 task owner. 3552 input.org: Explicit organization (`org_...`) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. 3553 input.task: Attributes for the task to create. `name` is required; all other fields are optional. 3554 input.team: Team ID (`tem_...`). The task will be owned by this team. 3555 3556 Returns: 3557 The newly created task. 3558 """ 3559 return self._http.request( 3560 f"/api/v1/users/{user}/tasks", 3561 method="POST", 3562 body=input, 3563 response_type=Task, 3564 )
Create a task for an owner
Creates a new task owned by the specified user or team and returns the full
task object. User-authenticated calls are attributed to the authenticated
user or agent. App-scoped developer and server-to-server callers must provide
the task's explicit org scope and an explicit user or agent actor for
team tasks; a user-owned task reuses the user in the route unless an explicit
agent is supplied. Every referenced principal is validated against the app,
owner, and team membership before creation.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - 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 task owner. - input.org: Explicit organization (
org_...) for developer and server-to-server calls. Pass null when the owner is not organization-scoped. The value must match the selected user or team. - input.task: Attributes for the task to create.
nameis required; all other fields are optional. - input.team: Team ID (
tem_...). The task will be owned by this team.
Returns:
The newly created task.
def
blocker_cycles( self, user: str, *, team: str | None = None, org: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> UserTaskBlockerCyclesResponse:
3566 def blocker_cycles( 3567 self, 3568 user: str, 3569 *, 3570 team: str | None = None, 3571 org: str | None = None, 3572 limit: int | None = None, 3573 after_cursor: str | None = None, 3574 ) -> UserTaskBlockerCyclesResponse: 3575 """ 3576 List task blocker cycles 3577 Runs an on-demand diagnostic over unfinished tasks owned by the specified 3578 team or user and returns a forward cursor-paginated page of complete cyclic 3579 blocker components. Detection is bounded to owners with at most 100 3580 unfinished tasks. This endpoint is read-only: cycles do not prevent task 3581 updates, lease acquisition, or completion. 3582 3583 Args: 3584 user: User ID (`usr_...`) for user-scoped tasks. 3585 team: Team ID (`tem_...`) owning the tasks. 3586 org: Optional organization context for privileged callers. 3587 limit: Maximum cycle components to return. Defaults to 50; maximum is 100. 3588 after_cursor: Opaque cursor returned by the preceding page. 3589 3590 Returns: 3591 Successful response 3592 """ 3593 query: dict[str, object] = {} 3594 if team is not None: 3595 query["team"] = team 3596 if org is not None: 3597 query["org"] = org 3598 if limit is not None: 3599 query["limit"] = limit 3600 if after_cursor is not None: 3601 query["after_cursor"] = after_cursor 3602 return self._http.request( 3603 f"/api/v1/users/{user}/tasks/blocker_cycles", 3604 query=query, 3605 response_type=UserTaskBlockerCyclesResponse, 3606 )
List task blocker cycles Runs an on-demand diagnostic over unfinished tasks owned by the specified team or user and returns a forward cursor-paginated page of complete cyclic blocker components. Detection is bounded to owners with at most 100 unfinished tasks. This endpoint is read-only: cycles do not prevent task updates, lease acquisition, or completion.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...) owning the tasks. - org: Optional organization context for privileged callers.
- 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
ready( self, user: str, *, team: str | None = None, org: str | None = None, 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) -> UserTaskReadyResponse:
3608 def ready( 3609 self, 3610 user: str, 3611 *, 3612 team: str | None = None, 3613 org: str | None = None, 3614 explain: bool | None = None, 3615 assigned_to_me: bool | None = None, 3616 source_scope: str | None = None, 3617 source_type: str | None = None, 3618 source_id: str | None = None, 3619 epic: str | None = None, 3620 limit: int | None = None, 3621 after_cursor: str | None = None, 3622 ) -> UserTaskReadyResponse: 3623 """ 3624 List an owner's ready tasks 3625 Returns open tasks with no unfinished blockers and no active session lease. 3626 Readiness is calculated by the server from the current task projection. It is 3627 a snapshot, not a reservation; claim a task lease before starting work. 3628 Pass `explain=true` to include every open task with a stable readiness reason. 3629 3630 Args: 3631 user: User ID (`usr_...`) for user-scoped tasks. 3632 team: Team ID (`tem_...`) owning the tasks. 3633 org: Optional organization context for privileged callers. 3634 explain: Include blocked and actively leased open tasks with exclusion reasons. 3635 assigned_to_me: Only include tasks assigned to the authenticated user. 3636 source_scope: Only include tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3637 source_type: Only include tasks whose source matches this object kind. 3638 source_id: Only include tasks whose source matches this object identity. 3639 epic: Only include tasks with this exact epic label. 3640 limit: Maximum number of readiness entries to return. Capped at 100. 3641 after_cursor: Opaque cursor returned by the previous page. 3642 3643 Returns: 3644 Successful response 3645 """ 3646 query: dict[str, object] = {} 3647 if team is not None: 3648 query["team"] = team 3649 if org is not None: 3650 query["org"] = org 3651 if explain is not None: 3652 query["explain"] = explain 3653 if assigned_to_me is not None: 3654 query["assigned_to_me"] = assigned_to_me 3655 if source_scope is not None: 3656 query["source_scope"] = source_scope 3657 if source_type is not None: 3658 query["source_type"] = source_type 3659 if source_id is not None: 3660 query["source_id"] = source_id 3661 if epic is not None: 3662 query["epic"] = epic 3663 if limit is not None: 3664 query["limit"] = limit 3665 if after_cursor is not None: 3666 query["after_cursor"] = after_cursor 3667 return self._http.request( 3668 f"/api/v1/users/{user}/tasks/ready", 3669 query=query, 3670 response_type=UserTaskReadyResponse, 3671 )
List an owner's ready tasks
Returns open tasks with no unfinished blockers and no active session lease.
Readiness is calculated by the server from the current task projection. It is
a snapshot, not a reservation; claim a task lease before starting work.
Pass explain=true to include every open task with a stable readiness reason.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...) owning the tasks. - org: Optional organization context for privileged callers.
- 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, user: str, *, team: str | None = None, org: str | None = None, 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) -> UserTaskSearchResponse:
3673 def search( 3674 self, 3675 user: str, 3676 *, 3677 team: str | None = None, 3678 org: str | None = None, 3679 q: str | None = None, 3680 query: str | None = None, 3681 status: str | None = None, 3682 owner_user: str | None = None, 3683 owner_agent: str | None = None, 3684 priority: int | None = None, 3685 tag: str | None = None, 3686 parent: str | None = None, 3687 source_scope: str | None = None, 3688 source_type: str | None = None, 3689 source_id: str | None = None, 3690 epic: str | None = None, 3691 limit: int | None = None, 3692 after_cursor: str | None = None, 3693 ) -> UserTaskSearchResponse: 3694 """ 3695 Search an owner's tasks 3696 Performs a full-text search over tasks owned by the specified user or team and returns 3697 matching results. Combine `q` with the optional filters to narrow the result set 3698 further. When no query is provided, the endpoint behaves like a filtered list. 3699 The `query` field in the response echoes the effective search query. 3700 User-authenticated callers may search their personal tasks or tasks for teams 3701 they have joined. Privileged callers provide the owner in the route; the owner's 3702 organization is implied by that principal. An explicit `org` is optional and, 3703 when set, must match the owner's organization. 3704 3705 Args: 3706 user: User ID (`usr_...`) for user-scoped tasks. 3707 team: Team ID (`tem_...`). Only tasks belonging to this team are searched. 3708 org: Optional organization (`org_...`) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. 3709 q: Full-text search query matched against task names and descriptions. Takes precedence over `query` when both are provided. 3710 query: Alias for `q`. Use `q` when possible; this parameter exists for compatibility. 3711 status: Filter results by status. One of `"open"`, `"in_progress"`, or `"done"`. Omit to include all statuses. 3712 owner_user: Restrict results to tasks assigned to the user with this public ID (`usr_...`). 3713 owner_agent: Restrict results to tasks assigned to the agent with this public ID (`agi_...`). 3714 priority: Filter results by priority, from 0 (highest) to 4 (lowest). 3715 tag: Return only tasks carrying this tag (matched against the canonical lowercase form). 3716 parent: Return only subtasks of the given task (`tsk_...`), or pass `none` to return only top-level tasks. 3717 source_scope: Return only tasks whose source matches this container. Must be supplied with `source_type` and `source_id`. 3718 source_type: Return only tasks whose source matches this object kind. 3719 source_id: Return only tasks whose source matches this object identity. 3720 epic: Return only tasks with this exact epic label. 3721 limit: Maximum number of tasks to return. Capped at 100. 3722 after_cursor: Opaque cursor returned by the previous page. 3723 3724 Returns: 3725 Successful response 3726 """ 3727 query: dict[str, object] = {} 3728 if team is not None: 3729 query["team"] = team 3730 if org is not None: 3731 query["org"] = org 3732 if q is not None: 3733 query["q"] = q 3734 if query is not None: 3735 query["query"] = query 3736 if status is not None: 3737 query["status"] = status 3738 if owner_user is not None: 3739 query["owner_user"] = owner_user 3740 if owner_agent is not None: 3741 query["owner_agent"] = owner_agent 3742 if priority is not None: 3743 query["priority"] = priority 3744 if tag is not None: 3745 query["tag"] = tag 3746 if parent is not None: 3747 query["parent"] = parent 3748 if source_scope is not None: 3749 query["source_scope"] = source_scope 3750 if source_type is not None: 3751 query["source_type"] = source_type 3752 if source_id is not None: 3753 query["source_id"] = source_id 3754 if epic is not None: 3755 query["epic"] = epic 3756 if limit is not None: 3757 query["limit"] = limit 3758 if after_cursor is not None: 3759 query["after_cursor"] = after_cursor 3760 return self._http.request( 3761 f"/api/v1/users/{user}/tasks/search", 3762 query=query, 3763 response_type=UserTaskSearchResponse, 3764 )
Search an owner's tasks
Performs a full-text search over tasks owned by the specified user or team and returns
matching results. Combine q with the optional filters to narrow the result set
further. When no query is provided, the endpoint behaves like a filtered list.
The query field in the response echoes the effective search query.
User-authenticated callers may search their personal tasks or tasks for teams
they have joined. Privileged callers provide the owner in the route; the owner's
organization is implied by that principal. An explicit org is optional and,
when set, must match the owner's organization.
Arguments:
- user: User ID (
usr_...) for user-scoped tasks. - team: Team ID (
tem_...). Only tasks belonging to this team are searched. - org: Optional organization (
org_...) for developer and server-to-server calls. When omitted, the org is taken from the owner principal (team, user, or agent). When set, it must match that principal's org; pass null for an owner outside an organization. - 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", or"done". Omit to include all statuses. - owner_user: Restrict results to tasks assigned to the user with this public ID (
usr_...). - owner_agent: Restrict results to tasks assigned to the agent with this public ID (
agi_...). - priority: Filter results 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.
- source_id: Return only tasks whose source matches this object identity.
- 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
UserThreadResource:
3767class UserThreadResource: 3768 def __init__(self, http: SyncHttpClient): 3769 self._http = http 3770 3771 def list( 3772 self, 3773 user: str, 3774 *, 3775 agent: builtins.list[str] | None = None, 3776 filter: builtins.list[dict[str, Any]] | None = None, 3777 ) -> UserThreadListResponse: 3778 """ 3779 List threads for a user 3780 Returns all threads visible to the specified user. The authenticated caller must 3781 have access to the target user's account; a 403 is returned otherwise. 3782 Pass one or more `agent` IDs to narrow results to threads where at least one of 3783 the listed agents is also a member useful for displaying every thread a user 3784 shares with a particular agent. Pass one or more `filter` objects to narrow 3785 results by thread metadata key/value pairs. Both narrowings may be combined in 3786 a single request. 3787 Results are returned as a flat array; no cursor-based pagination is applied. 3788 Threads are ordered with default threads first, then by most recent activity 3789 (newest first), each carrying a `last_activity` timestamp. 3790 3791 Args: 3792 user: User ID (`usr_...`) whose threads should be listed. 3793 agent: Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. 3794 filter: Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata. 3795 3796 Returns: 3797 Successful response 3798 """ 3799 query: dict[str, object] = {} 3800 if agent is not None: 3801 query["agent"] = agent 3802 if filter is not None: 3803 query["filter"] = filter 3804 return self._http.request( 3805 f"/api/v1/users/{user}/threads", 3806 query=query, 3807 response_type=UserThreadListResponse, 3808 ) 3809 3810 def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3811 """ 3812 Create a thread for a user 3813 Creates a new thread owned by the specified user. The authenticated caller must 3814 have access to the target user's account; a 403 is returned otherwise. 3815 An automatic welcome message is sent into the thread upon creation unless 3816 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3817 the owning user and any members added at creation time. 3818 3819 Args: 3820 user: User ID (`usr_...`) whose threads should be listed. 3821 input: Request body. 3822 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3823 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3824 3825 Returns: 3826 The newly created thread object. 3827 """ 3828 return self._http.request( 3829 f"/api/v1/users/{user}/threads", 3830 method="POST", 3831 body=input, 3832 response_type=Thread, 3833 )
UserThreadResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, user: str, *, agent: list[str] | None = None, filter: list[dict[str, typing.Any]] | None = None) -> UserThreadListResponse:
3771 def list( 3772 self, 3773 user: str, 3774 *, 3775 agent: builtins.list[str] | None = None, 3776 filter: builtins.list[dict[str, Any]] | None = None, 3777 ) -> UserThreadListResponse: 3778 """ 3779 List threads for a user 3780 Returns all threads visible to the specified user. The authenticated caller must 3781 have access to the target user's account; a 403 is returned otherwise. 3782 Pass one or more `agent` IDs to narrow results to threads where at least one of 3783 the listed agents is also a member useful for displaying every thread a user 3784 shares with a particular agent. Pass one or more `filter` objects to narrow 3785 results by thread metadata key/value pairs. Both narrowings may be combined in 3786 a single request. 3787 Results are returned as a flat array; no cursor-based pagination is applied. 3788 Threads are ordered with default threads first, then by most recent activity 3789 (newest first), each carrying a `last_activity` timestamp. 3790 3791 Args: 3792 user: User ID (`usr_...`) whose threads should be listed. 3793 agent: Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. 3794 filter: Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata. 3795 3796 Returns: 3797 Successful response 3798 """ 3799 query: dict[str, object] = {} 3800 if agent is not None: 3801 query["agent"] = agent 3802 if filter is not None: 3803 query["filter"] = filter 3804 return self._http.request( 3805 f"/api/v1/users/{user}/threads", 3806 query=query, 3807 response_type=UserThreadListResponse, 3808 )
List threads for a user
Returns all threads visible to the specified user. The authenticated caller must
have access to the target user's account; a 403 is returned otherwise.
Pass one or more agent IDs to narrow results to threads where at least one of
the listed agents is also a member useful for displaying every thread a user
shares with a particular agent. Pass one or more filter objects to narrow
results by thread metadata key/value pairs. Both narrowings may be combined in
a single request.
Results are returned as a flat array; no cursor-based pagination is applied.
Threads are ordered with default threads first, then by most recent activity
(newest first), each carrying a last_activity timestamp.
Arguments:
- user: User ID (
usr_...) whose threads should be listed. - agent: Array of agent user IDs (
usr_...). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership. - filter: Array of metadata filter objects. Each filter matches threads whose
metadatamap contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata.
Returns:
Successful response
def
create( self, user: str, input: UserThreadCreateInput) -> archastro.platform.types.threads.Thread:
3810 def create(self, user: str, input: UserThreadCreateInput) -> Thread: 3811 """ 3812 Create a thread for a user 3813 Creates a new thread owned by the specified user. The authenticated caller must 3814 have access to the target user's account; a 403 is returned otherwise. 3815 An automatic welcome message is sent into the thread upon creation unless 3816 `skip_welcome_message` is set to `true`. The thread is immediately visible to 3817 the owning user and any members added at creation time. 3818 3819 Args: 3820 user: User ID (`usr_...`) whose threads should be listed. 3821 input: Request body. 3822 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`. 3823 input.thread: Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields. 3824 3825 Returns: 3826 The newly created thread object. 3827 """ 3828 return self._http.request( 3829 f"/api/v1/users/{user}/threads", 3830 method="POST", 3831 body=input, 3832 response_type=Thread, 3833 )
Create a thread for a user
Creates a new thread owned by the specified user. The authenticated caller must
have access to the target user's account; a 403 is returned otherwise.
An automatic welcome message is sent into the thread upon creation unless
skip_welcome_message is set to true. The thread is immediately visible to
the owning user and any members added at creation time.
Arguments:
- user: User ID (
usr_...) whose 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. See ThreadCreateParams for the full set of accepted fields.
Returns:
The newly created thread object.
class
TokenResource:
3836class TokenResource: 3837 def __init__(self, http: SyncHttpClient): 3838 self._http = http 3839 3840 def list(self, user: str) -> TokenListResponse: 3841 """ 3842 List personal access tokens 3843 Returns all access tokens associated with the authenticated user, including 3844 active and revoked tokens. Tokens are returned without their raw JWT values 3845 the plaintext JWT is only available at creation time. 3846 The caller must be the user identified by `user` and must present a 3847 first-party session (or a `full_access` access token). 3848 3849 Args: 3850 user: User ID (`usr_...`) or `me` for the authenticated user. 3851 3852 Returns: 3853 Successful response 3854 """ 3855 return self._http.request(f"/api/v1/users/{user}/tokens", response_type=TokenListResponse) 3856 3857 def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3858 """ 3859 Create a personal access token 3860 Issues a new long-lived access token for the authenticated user. The raw 3861 JWT is returned in the `token` field of the response exactly once and 3862 cannot be retrieved again store it securely immediately after creation. 3863 `scopes` is optional. When omitted the token receives `full_access`. 3864 Known catalog scopes (for example `profile`) restrict the token through 3865 the same `ScopeGuard` used by OAuth. 3866 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3867 or `365`. When omitted the token lasts 30 days. Each user may hold at 3868 most 50 active tokens; exceeding that limit returns 429. 3869 The caller must be the user identified by `user` and must present a 3870 first-party session (or a `full_access` access token). A restricted 3871 access token cannot mint another token. 3872 3873 Args: 3874 user: User ID (`usr_...`) or `me` for the authenticated user. 3875 input: Request body. 3876 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3877 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3878 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3879 3880 Returns: 3881 The newly created access token. The `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. 3882 """ 3883 return self._http.request( 3884 f"/api/v1/users/{user}/tokens", 3885 method="POST", 3886 body=input, 3887 response_type=SystemAccessToken, 3888 ) 3889 3890 def delete(self, user: str, token: str) -> SystemAccessToken: 3891 """ 3892 Revoke a personal access token 3893 Permanently revokes the specified access token belonging to the 3894 authenticated user. Once revoked, the token is immediately rejected by 3895 all API endpoints and cannot be reinstated. The token record is retained 3896 and returned in the response with `revoked_at` populated. 3897 The caller must be the user identified by `user` and must present a 3898 first-party session (or a `full_access` access token). Returns 404 if 3899 the token does not exist or does not belong to the caller. 3900 3901 Args: 3902 user: User ID (`usr_...`) or `me` for the authenticated user. 3903 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3904 3905 Returns: 3906 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3907 """ 3908 return self._http.request( 3909 f"/api/v1/users/{user}/tokens/{token}", 3910 method="DELETE", 3911 response_type=SystemAccessToken, 3912 )
TokenResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
3840 def list(self, user: str) -> TokenListResponse: 3841 """ 3842 List personal access tokens 3843 Returns all access tokens associated with the authenticated user, including 3844 active and revoked tokens. Tokens are returned without their raw JWT values 3845 the plaintext JWT is only available at creation time. 3846 The caller must be the user identified by `user` and must present a 3847 first-party session (or a `full_access` access token). 3848 3849 Args: 3850 user: User ID (`usr_...`) or `me` for the authenticated user. 3851 3852 Returns: 3853 Successful response 3854 """ 3855 return self._http.request(f"/api/v1/users/{user}/tokens", response_type=TokenListResponse)
List personal access tokens
Returns all access tokens associated with the authenticated user, including
active and revoked tokens. Tokens are returned without their raw JWT values
the plaintext JWT is only available at creation time.
The caller must be the user identified by user and must present a
first-party session (or a full_access access token).
Arguments:
- user: User ID (
usr_...) ormefor the authenticated user.
Returns:
Successful response
def
create( self, user: str, input: TokenCreateInput) -> archastro.platform.types.system.SystemAccessToken:
3857 def create(self, user: str, input: TokenCreateInput) -> SystemAccessToken: 3858 """ 3859 Create a personal access token 3860 Issues a new long-lived access token for the authenticated user. The raw 3861 JWT is returned in the `token` field of the response exactly once and 3862 cannot be retrieved again store it securely immediately after creation. 3863 `scopes` is optional. When omitted the token receives `full_access`. 3864 Known catalog scopes (for example `profile`) restrict the token through 3865 the same `ScopeGuard` used by OAuth. 3866 `expires_in_days` is optional and must be one of `7`, `30`, `60`, `90`, 3867 or `365`. When omitted the token lasts 30 days. Each user may hold at 3868 most 50 active tokens; exceeding that limit returns 429. 3869 The caller must be the user identified by `user` and must present a 3870 first-party session (or a `full_access` access token). A restricted 3871 access token cannot mint another token. 3872 3873 Args: 3874 user: User ID (`usr_...`) or `me` for the authenticated user. 3875 input: Request body. 3876 input.expires_in_days: Lifetime in days. One of `7`, `30`, `60`, `90`, or `365`. Defaults to `30`. 3877 input.name: Human-readable label for the token (e.g. `"Codex MCP"`). Stored as metadata only. 3878 input.scopes: Optional OAuth scopes to stamp on the token. Omit for `full_access`. 3879 3880 Returns: 3881 The newly created access token. The `token` field contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later. 3882 """ 3883 return self._http.request( 3884 f"/api/v1/users/{user}/tokens", 3885 method="POST", 3886 body=input, 3887 response_type=SystemAccessToken, 3888 )
Create a personal access token
Issues a new long-lived access token for the authenticated user. The raw
JWT is returned in the token field of the response exactly once and
cannot be retrieved again store it securely immediately after creation.
scopes is optional. When omitted the token receives full_access.
Known catalog scopes (for example profile) restrict the token through
the same ScopeGuard used by OAuth.
expires_in_days is optional and must be one of 7, 30, 60, 90,
or 365. When omitted the token lasts 30 days. Each user may hold at
most 50 active tokens; exceeding that limit returns 429.
The caller must be the user identified by user and must present a
first-party session (or a full_access access token). A restricted
access token cannot mint another token.
Arguments:
- user: User ID (
usr_...) ormefor the authenticated user. - input: Request body.
- input.expires_in_days: Lifetime in days. One of
7,30,60,90, or365. Defaults to30. - input.name: Human-readable label for the token (e.g.
"Codex MCP"). Stored as metadata only. - input.scopes: Optional OAuth scopes to stamp on the token. Omit for
full_access.
Returns:
The newly created access token. The
tokenfield contains the raw JWT and is present only in this response it is not stored and cannot be retrieved later.
3890 def delete(self, user: str, token: str) -> SystemAccessToken: 3891 """ 3892 Revoke a personal access token 3893 Permanently revokes the specified access token belonging to the 3894 authenticated user. Once revoked, the token is immediately rejected by 3895 all API endpoints and cannot be reinstated. The token record is retained 3896 and returned in the response with `revoked_at` populated. 3897 The caller must be the user identified by `user` and must present a 3898 first-party session (or a `full_access` access token). Returns 404 if 3899 the token does not exist or does not belong to the caller. 3900 3901 Args: 3902 user: User ID (`usr_...`) or `me` for the authenticated user. 3903 token: Access token ID (`sat_...`). Must belong to the authenticated user. 3904 3905 Returns: 3906 The revoked access token. The `revoked_at` field is populated with the time of revocation. 3907 """ 3908 return self._http.request( 3909 f"/api/v1/users/{user}/tokens/{token}", 3910 method="DELETE", 3911 response_type=SystemAccessToken, 3912 )
Revoke a personal access token
Permanently revokes the specified access token belonging to the
authenticated user. Once revoked, the token is immediately rejected by
all API endpoints and cannot be reinstated. The token record is retained
and returned in the response with revoked_at populated.
The caller must be the user identified by user and must present a
first-party session (or a full_access access token). Returns 404 if
the token does not exist or does not belong to the caller.
Arguments:
- user: User ID (
usr_...) ormefor the authenticated user. - token: Access token ID (
sat_...). Must belong to the authenticated user.
Returns:
The revoked access token. The
revoked_atfield is populated with the time of revocation.
class
UserResource:
3915class UserResource: 3916 def __init__(self, http: SyncHttpClient): 3917 self._http = http 3918 self.tasks = UserTaskResource(http) 3919 self.threads = UserThreadResource(http) 3920 self.tokens = TokenResource(http) 3921 3922 def me(self) -> User: 3923 """ 3924 Retrieve the current user 3925 Returns the user associated with the authenticated session or bearer 3926 token. This is the canonical way to resolve "who am I?" after 3927 authentication. 3928 The response includes the user's profile, notification settings, and 3929 profile picture, along with the app, organization, and sandbox the 3930 token is scoped to and their display names enough to establish full 3931 session context in a single call. Unauthenticated requests return 401. 3932 3933 Returns: 3934 The authenticated user object. 3935 """ 3936 return self._http.request("/api/v1/users/me", response_type=User) 3937 3938 def get(self, user: str) -> User: 3939 """ 3940 Retrieve a user by ID 3941 Returns the user identified by `user`. The authenticated user must share 3942 at least one team with the target user; requests for users outside any 3943 shared team are rejected with 403. 3944 A user may always retrieve their own profile with this endpoint. Use the 3945 `GET /users/me` endpoint as a convenience alias for retrieving the 3946 authenticated user without specifying an ID. 3947 3948 Args: 3949 user: User ID (`usr_...`) of the user to retrieve. 3950 3951 Returns: 3952 The requested user object. 3953 """ 3954 return self._http.request(f"/api/v1/users/{user}", response_type=User) 3955 3956 def artifacts(self, user: str) -> UserArtifactsResponse: 3957 """ 3958 List a user's artifacts 3959 Returns all artifacts owned by the specified user. Artifacts represent 3960 AI-generated or user-uploaded files associated with agent sessions, 3961 threads, or sandboxes such as images, documents, and code outputs. 3962 The authenticated user must be requesting their own artifacts or must 3963 have administrative access. Attempting to list artifacts for a user 3964 the caller is not authorized to access returns 403. 3965 Results are returned in a single page without cursor pagination. Each 3966 artifact in the response reflects the state of its current version, 3967 including a short-lived signed `file_url` for direct download. 3968 3969 Args: 3970 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3971 3972 Returns: 3973 Successful response 3974 """ 3975 return self._http.request( 3976 f"/api/v1/users/{user}/artifacts", 3977 response_type=UserArtifactsResponse, 3978 ) 3979 3980 def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3981 """ 3982 Create a user invite 3983 Creates a new invite for the authenticated user. The invite can optionally be 3984 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3985 caller receives the new invite object at HTTP 201. 3986 The invite key is always generated server-side (192-bit URL-safe random 3987 string) and cannot be supplied by the caller. 3988 The path `:user` must match the authenticated user. If a `thread_id` is 3989 provided, the authenticated user must have permission to invite others to that 3990 thread; team threads are not supported and return an error. Supplying a 3991 `thread_id` that does not exist or that belongs to a different user returns 3992 an error. If a key collision occurs during creation the call returns a 409 3993 conflict simply retry to generate a new key. 3994 3995 Args: 3996 user: User ID (`usr_...`). Must match the authenticated user. 3997 input: Request body. 3998 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3999 4000 Returns: 4001 The newly created invite object. 4002 """ 4003 return self._http.request( 4004 f"/api/v1/users/{user}/invites", 4005 method="POST", 4006 body=input, 4007 response_type=UserInvite, 4008 ) 4009 4010 def orgs(self, user: str) -> UserOrgsResponse: 4011 """ 4012 List organizations for a user 4013 Returns the organizations the specified user belongs to. A user can belong 4014 to at most one organization, so the `data` array contains either zero or one 4015 items. 4016 The authenticated viewer must have permission to inspect the target user. 4017 Returns an empty `data` array when the user has no organization membership. 4018 4019 Args: 4020 user: User ID (`usr_...`) whose organization membership you want to retrieve. 4021 4022 Returns: 4023 Successful response 4024 """ 4025 return self._http.request(f"/api/v1/users/{user}/orgs", response_type=UserOrgsResponse) 4026 4027 def profile(self, user: str, input: UserProfileInput) -> User: 4028 """ 4029 Update the current user's profile 4030 Updates one or more profile fields for the authenticated user. All 4031 fields are optional; omit any you do not want to change. 4032 When `profile_picture` is supplied, the image is uploaded and replaces 4033 the existing picture. The previous picture is deleted after the new one 4034 is stored. Image upload failures return 422 without modifying other 4035 profile fields. 4036 4037 Args: 4038 user: User ID (`usr_...`) or `"me"` for the authenticated user. 4039 input: Request body. 4040 input.alias: Short display alias shown in place of the full name in compact UI contexts. 4041 input.full_name: Updated display name for the user. 4042 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 4043 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 4044 4045 Returns: 4046 The user object with updated profile fields. 4047 """ 4048 return self._http.request( 4049 f"/api/v1/users/{user}/profile", 4050 method="PUT", 4051 body=input, 4052 response_type=User, 4053 )
UserResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
3922 def me(self) -> User: 3923 """ 3924 Retrieve the current user 3925 Returns the user associated with the authenticated session or bearer 3926 token. This is the canonical way to resolve "who am I?" after 3927 authentication. 3928 The response includes the user's profile, notification settings, and 3929 profile picture, along with the app, organization, and sandbox the 3930 token is scoped to and their display names enough to establish full 3931 session context in a single call. Unauthenticated requests return 401. 3932 3933 Returns: 3934 The authenticated user object. 3935 """ 3936 return self._http.request("/api/v1/users/me", response_type=User)
Retrieve the current user Returns the user associated with the authenticated session or bearer token. This is the canonical way to resolve "who am I?" after authentication. The response includes the user's profile, notification settings, and profile picture, along with the app, organization, and sandbox the token is scoped to and their display names enough to establish full session context in a single call. Unauthenticated requests return 401.
Returns:
The authenticated user object.
3938 def get(self, user: str) -> User: 3939 """ 3940 Retrieve a user by ID 3941 Returns the user identified by `user`. The authenticated user must share 3942 at least one team with the target user; requests for users outside any 3943 shared team are rejected with 403. 3944 A user may always retrieve their own profile with this endpoint. Use the 3945 `GET /users/me` endpoint as a convenience alias for retrieving the 3946 authenticated user without specifying an ID. 3947 3948 Args: 3949 user: User ID (`usr_...`) of the user to retrieve. 3950 3951 Returns: 3952 The requested user object. 3953 """ 3954 return self._http.request(f"/api/v1/users/{user}", response_type=User)
Retrieve a user by ID
Returns the user identified by user. The authenticated user must share
at least one team with the target user; requests for users outside any
shared team are rejected with 403.
A user may always retrieve their own profile with this endpoint. Use the
GET /users/me endpoint as a convenience alias for retrieving the
authenticated user without specifying an ID.
Arguments:
- user: User ID (
usr_...) of the user to retrieve.
Returns:
The requested user object.
3956 def artifacts(self, user: str) -> UserArtifactsResponse: 3957 """ 3958 List a user's artifacts 3959 Returns all artifacts owned by the specified user. Artifacts represent 3960 AI-generated or user-uploaded files associated with agent sessions, 3961 threads, or sandboxes such as images, documents, and code outputs. 3962 The authenticated user must be requesting their own artifacts or must 3963 have administrative access. Attempting to list artifacts for a user 3964 the caller is not authorized to access returns 403. 3965 Results are returned in a single page without cursor pagination. Each 3966 artifact in the response reflects the state of its current version, 3967 including a short-lived signed `file_url` for direct download. 3968 3969 Args: 3970 user: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts. 3971 3972 Returns: 3973 Successful response 3974 """ 3975 return self._http.request( 3976 f"/api/v1/users/{user}/artifacts", 3977 response_type=UserArtifactsResponse, 3978 )
List a user's artifacts
Returns all artifacts owned by the specified user. Artifacts represent
AI-generated or user-uploaded files associated with agent sessions,
threads, or sandboxes such as images, documents, and code outputs.
The authenticated user must be requesting their own artifacts or must
have administrative access. Attempting to list artifacts for a user
the caller is not authorized to access returns 403.
Results are returned in a single page without cursor pagination. Each
artifact in the response reflects the state of its current version,
including a short-lived signed file_url for direct download.
Arguments:
- user: User ID (
usr_...). The authenticated user must be this user or have access to their artifacts.
Returns:
Successful response
def
invites( self, user: str, input: UserInvitesInput) -> archastro.platform.types.users.UserInvite:
3980 def invites(self, user: str, input: UserInvitesInput) -> UserInvite: 3981 """ 3982 Create a user invite 3983 Creates a new invite for the authenticated user. The invite can optionally be 3984 scoped to a specific thread, a persona, or carry arbitrary metadata. The 3985 caller receives the new invite object at HTTP 201. 3986 The invite key is always generated server-side (192-bit URL-safe random 3987 string) and cannot be supplied by the caller. 3988 The path `:user` must match the authenticated user. If a `thread_id` is 3989 provided, the authenticated user must have permission to invite others to that 3990 thread; team threads are not supported and return an error. Supplying a 3991 `thread_id` that does not exist or that belongs to a different user returns 3992 an error. If a key collision occurs during creation the call returns a 409 3993 conflict simply retry to generate a new key. 3994 3995 Args: 3996 user: User ID (`usr_...`). Must match the authenticated user. 3997 input: Request body. 3998 input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details. 3999 4000 Returns: 4001 The newly created invite object. 4002 """ 4003 return self._http.request( 4004 f"/api/v1/users/{user}/invites", 4005 method="POST", 4006 body=input, 4007 response_type=UserInvite, 4008 )
Create a user invite
Creates a new invite for the authenticated user. The invite can optionally be
scoped to a specific thread, a persona, or carry arbitrary metadata. The
caller receives the new invite object at HTTP 201.
The invite key is always generated server-side (192-bit URL-safe random
string) and cannot be supplied by the caller.
The path :user must match the authenticated user. If a thread_id is
provided, the authenticated user must have permission to invite others to that
thread; team threads are not supported and return an error. Supplying a
thread_id that does not exist or that belongs to a different user returns
an error. If a key collision occurs during creation the call returns a 409
conflict simply retry to generate a new key.
Arguments:
- user: User ID (
usr_...). Must match the authenticated user. - input: Request body.
- input.invite: Parameters for the new invite. See the UserInviteCreateParams schema for field details.
Returns:
The newly created invite object.
4010 def orgs(self, user: str) -> UserOrgsResponse: 4011 """ 4012 List organizations for a user 4013 Returns the organizations the specified user belongs to. A user can belong 4014 to at most one organization, so the `data` array contains either zero or one 4015 items. 4016 The authenticated viewer must have permission to inspect the target user. 4017 Returns an empty `data` array when the user has no organization membership. 4018 4019 Args: 4020 user: User ID (`usr_...`) whose organization membership you want to retrieve. 4021 4022 Returns: 4023 Successful response 4024 """ 4025 return self._http.request(f"/api/v1/users/{user}/orgs", response_type=UserOrgsResponse)
List organizations for a user
Returns the organizations the specified user belongs to. A user can belong
to at most one organization, so the data array contains either zero or one
items.
The authenticated viewer must have permission to inspect the target user.
Returns an empty data array when the user has no organization membership.
Arguments:
- user: User ID (
usr_...) whose organization membership you want to retrieve.
Returns:
Successful response
4027 def profile(self, user: str, input: UserProfileInput) -> User: 4028 """ 4029 Update the current user's profile 4030 Updates one or more profile fields for the authenticated user. All 4031 fields are optional; omit any you do not want to change. 4032 When `profile_picture` is supplied, the image is uploaded and replaces 4033 the existing picture. The previous picture is deleted after the new one 4034 is stored. Image upload failures return 422 without modifying other 4035 profile fields. 4036 4037 Args: 4038 user: User ID (`usr_...`) or `"me"` for the authenticated user. 4039 input: Request body. 4040 input.alias: Short display alias shown in place of the full name in compact UI contexts. 4041 input.full_name: Updated display name for the user. 4042 input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it. 4043 input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture. 4044 4045 Returns: 4046 The user object with updated profile fields. 4047 """ 4048 return self._http.request( 4049 f"/api/v1/users/{user}/profile", 4050 method="PUT", 4051 body=input, 4052 response_type=User, 4053 )
Update the current user's profile
Updates one or more profile fields for the authenticated user. All
fields are optional; omit any you do not want to change.
When profile_picture is supplied, the image is uploaded and replaces
the existing picture. The previous picture is deleted after the new one
is stored. Image upload failures return 422 without modifying other
profile fields.
Arguments:
- user: User ID (
usr_...) or"me"for the authenticated user. - input: Request body.
- input.alias: Short display alias shown in place of the full name in compact UI contexts.
- input.full_name: Updated display name for the user.
- input.metadata: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass
nullfor a key to remove it. - input.profile_picture: New profile picture to upload as a base64-encoded image. Replaces any existing picture.
Returns:
The user object with updated profile fields.